diff --git a/.agent/skills/merovingian-review/references/module-invariants.md b/.agent/skills/merovingian-review/references/module-invariants.md index 03cec530b..b5a26f86f 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 @@ -105,6 +108,10 @@ 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). 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 @@ -179,6 +186,17 @@ 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). 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). 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). 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-0812, 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` @@ -239,6 +257,26 @@ look at every time. Read the `AGENTS.md` itself before judging a change to that most 1/16 of the parked budget (ADR-0719). - Shutdown order: stop accepting, stop the parker, drain the pools. +## src/oauth + +- 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 + 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). +- 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` +- 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 - Never log secrets. One record is one physical line. Field values are capped. URLs are logged without the query. @@ -297,6 +335,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/AGENTS.md b/AGENTS.md index a77e1c855..f7e4e3986 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,6 +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, 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 @@ -223,7 +224,7 @@ the same name in `include/`: `src/appservice/RegistrationYaml.cpp`, `src/databas │ ├── smoke/ # Smoke tests │ ├── password_cost/ # Proves the production Argon2id cost, in a binary without the tests' cheap hash │ ├── complement/ # Docker image that runs the release package under Complement -│ ├── fixtures/ # Test fixtures: complement/ (JSON flow fixtures) and upgrade/ (README only; no cross-release database fixture until 1.1) +│ ├── fixtures/ # Test fixtures: complement/ (JSON flow fixtures) and upgrade/ (README only; the 1.0.x cross-release database fixture is not generated yet, the build VM has no PostgreSQL server) │ ├── support/ # Test helpers (JsonTestSupport, MasterKey, RegistrationToken, TempDirectory, TlsMockServer) │ ├── sanitizer/ # Sanitizer suppression files (tsan.supp) │ └── tooling/ # Python tests for CI workflows, dependency wraps, example config, logger filter @@ -276,6 +277,7 @@ More specific guidance lives alongside the code it governs. Read the relevant fi | `src/ipc/AGENTS.md` | Worker IPC: authenticated handshake, AEAD framing, reader/dispatch thread split | | `src/media/AGENTS.md` | Media: internal pipe format, MIME policy, quarantine, thumbnail worker | | `src/net/AGENTS.md` | Network: TCP acceptor, thread pool, graceful shutdown, CLOEXEC | +| `src/oauth/AGENTS.md` | OAuth 2.0: pure validators, strict URI reader, byte-exact redirect matching, escaped-by-type page renderer | | `src/observability/AGENTS.md` | Logging: level policy, audit events, secret redaction | | `src/platform/AGENTS.md` | Platform hardening: seccomp, pledge/Capsicum, ELF probe, self-check, file metadata safety | | `src/push/AGENTS.md` | Push: pure rule evaluation, gateway SSRF and URL rules, delivery caps | diff --git a/CHANGELOG.md b/CHANGELOG.md index a2c042d6c..8fda24d24 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,152 @@ 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 + +* A built-in OAuth 2.0 API, which Element X needs to create accounts, planned in `docs/todos/oauth-2-0-api.md` + (ADR-0812 to ADR-0816). +* 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-0817, 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). +* 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. +* 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). +* `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. +* 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 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 + browser back to the client with an authorization code or an error (ADR-0787, ADR-0789). +* Every OAuth authorisation asks for the password; a sign-in is bound to its browser by a `__Host-` cookie and the + 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). +* `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). +* 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). +* `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). +* `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). +* 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. +* The OAuth 2.0 plan records phases 1 to 10 as done and lists what is still open: Element X, PostgreSQL and the + upgrade fixture, QR-code login, the documentation site and `response_mode`. + +## 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). +* 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). +* 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. +* 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 + +* 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 + 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). +* 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. +* The server builds on FreeBSD again: the exception type name of ADR-0803 now includes ``, which FreeBSD's + `cxxabi.h` does not. +* 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-0817). +* The device and token inserts of a login, a grant and a refresh share one statement each; the SQL is unchanged. +* `POST /register` works again on FreeBSD's 64 KiB locked-memory limit: the OAuth client ID key is derived per + registration, not locked for life, and an unreadable token file logs `registration.token_file_unusable` (ADR-0779). +* The FreeBSD rc.d script sets the service's locked-memory limit itself (`merovingian_limits`, default `-l 128m`), + so the room for secrets no longer depends on the login class; `rc.conf` can override it. +* The PostgreSQL role tests remove the whole schema, not only the v1 tables, before they bootstrap it again: the + tables of migration 002 were left behind and the next open failed creating them. +* The compile-time checks of `HtmlLiteral`, `HtmlName` and `PagePath` throw `std::logic_error`, not a string + literal, so a check that does run at run time is caught as a standard exception. +* The percent-escape decoders of `FormFields` and `ParsedUri` advance by the bytes each branch read, and + `ClientMetadata::validate` and `ParsedUri::read` say why each step is there (CodeQL). +* `PendingAuthorisationStore::find` and `record_user` no longer name a hash they do not use; twelve long OAuth + test scenarios gained comments and three test helpers were tidied (CodeQL). + +## 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-0816). 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. 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.3 ## Features diff --git a/config/merovingian.conf.bsd.example b/config/merovingian.conf.bsd.example index 03150b5a5..072879541 100644 --- a/config/merovingian.conf.bsd.example +++ b/config/merovingian.conf.bsd.example @@ -629,24 +629,26 @@ 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) +# 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 +# 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 +# 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..598867b3d 100644 --- a/config/merovingian.conf.example +++ b/config/merovingian.conf.example @@ -602,24 +602,26 @@ 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) +# 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 +# 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 +# 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/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/0766-a-malformed-or-repeated-cookie-makes-only-its-own-name-unusable.md b/docs/adr/0766-a-malformed-or-repeated-cookie-makes-only-its-own-name-unusable.md new file mode 100644 index 000000000..4f65cfb2c --- /dev/null +++ b/docs/adr/0766-a-malformed-or-repeated-cookie-makes-only-its-own-name-unusable.md @@ -0,0 +1,66 @@ +# A malformed or repeated cookie makes only its own name unusable + +* Status: accepted +* Date: 2026-11-15 + +Technical Story: phase 1 of the OAuth 2.0 API plan (`docs/todos/oauth-2-0-api.md`) + +## Context and Problem Statement + +The OAuth 2.0 pages bind a pending authorisation, and the account pages a session, to the browser with `__Host-` +cookies. The `Cookie` header that comes back holds every cookie whose domain matches this host, including cookies a +sibling host under the same parent domain set with `Domain=` (cookie tossing): their names, values and number are +not this server's to choose, and many real sites set values with spaces, commas or quotes. How strict should the +reader be, and what does a repeated name mean? + +## Decision Drivers + +* No second value may be smuggled past a check of the first. +* A cookie that some other site set must not stop this server's pages from working. +* RFC 6265 section 5.4 sends cookies of the same name with no way for the server to tell which is which. + +## Considered Options + +* Refuse the whole header on any malformed pair or repeated name. +* Take the first (or last) value of a repeated name, and read malformed pairs leniently. +* Read each pair strictly, and make a malformed or repeated name unusable without refusing the others. + +## Decision Outcome + +Chosen option: "make a malformed or repeated name unusable", `core::RequestCookies`. `find(name)` answers only when +exactly one pair has that name and that pair is well-formed: the name an RFC 9110 token and the value unquoted +`*cookie-octet`. A quoted value is malformed, since this server never sets one. Empty pairs (`;;`) are skipped. The +header is refused whole only for what no browser sends: a control character other than a tab, more than 32 KiB, or +more than 256 pairs. Values are returned without percent-decoding and wiped when destroyed. The only writer, +`core::host_cookie`, can produce nothing but a `__Host-` cookie with `Secure`, `HttpOnly` and `Path=/`, so no other +host can set a cookie under one of this server's names, and a page that reads its own cookie as absent asks the user to +start again. + +### Positive Consequences + +* A tossed cookie under one of this server's names makes that name absent (the flow restarts); it can never supply + the value. +* Other sites' cookies, well-formed or not, do not affect this server. + +### Negative Consequences + +* A browser that holds two cookies of one name (possible only if one was set by this host without the prefix) cannot + use the page until one expires. Every cookie this server sets has the prefix, so this does not arise from its own + cookies. + +## Pros and Cons of the Options + +### Refuse the whole header + +* Good, because it is the simplest rule. +* Bad, because any site under the parent domain could stop sign-in for every visitor by setting one odd cookie. + +### First or last value wins + +* Good, because it matches several frameworks. +* Bad, because which copy a browser sends first depends on path length and creation time, which an attacker can + arrange, so the check and the use can disagree. + +## Links + +* Refines [ADR-0812](0812-the-oauth-2-0-api-is-built-into-the-homeserver.md) diff --git a/docs/adr/0767-a-response-head-the-formatter-cannot-write-safely-is-refused-with-a-500.md b/docs/adr/0767-a-response-head-the-formatter-cannot-write-safely-is-refused-with-a-500.md new file mode 100644 index 000000000..c73e8d784 --- /dev/null +++ b/docs/adr/0767-a-response-head-the-formatter-cannot-write-safely-is-refused-with-a-500.md @@ -0,0 +1,64 @@ +# A response head the formatter cannot write safely is refused with a 500 + +* Status: accepted +* Date: 2026-11-15 + +Technical Story: phase 1 of the OAuth 2.0 API plan (`docs/todos/oauth-2-0-api.md`) + +## Context and Problem Statement + +`format_response_head` in `homeserver/HttpServer.cpp` replaced the default `Content-Type` only when a handler spelled +the header exactly `Content-Type`, so `content-type` produced two. It skipped a header whose name or value was invalid +without a word, so a `Location` or `Content-Security-Policy` holding a CR would vanish from the response. It wrote a +handler's `Content-Length` or `Connection` beside its own, and a federation worker, the process most exposed to hostile +traffic, chooses the headers of every answer it relays. The OAuth 2.0 pages will set `Content-Type`, +`Content-Security-Policy`, `Set-Cookie` and `Location` on 200, 302 and 303 responses. What should the formatter do with +a header it cannot write safely? + +## Decision Drivers + +* A response must never carry two `Content-Type` headers, or two framings. +* Dropping a header silently can remove a security control (a content security policy, a cookie deletion). +* Header names are case-insensitive (RFC 9110 section 5.1). + +## Considered Options + +* Keep dropping invalid headers, and only fold the `Content-Type` match. +* Repair: strip CR and LF from values, keep the last `Content-Type`. +* Refuse: answer a fixed 500 and close the connection. + +## Decision Outcome + +Chosen option: "refuse". `http::format_response_head` (moved to `http/ResponseHead.hpp` so it can be tested) matches +names case-insensitively and returns an error, written by `HttpServer.cpp` as a logged `response.head_refused`, a fixed +`500 M_UNKNOWN` with no handler header and `Connection: close`, when the status is outside 200-599, a name is not a +token, a value holds a control character other than HTAB, a handler sets `Content-Length`, `Transfer-Encoding`, +`Connection` or `Keep-Alive`, or `Content-Type` or `X-Content-Type-Options` comes twice (the latter also when it is not +`nosniff`). An empty `Content-Type` still means the default. An unlisted status is written with an empty reason phrase +instead of `OK`. + +### Positive Consequences + +* A handler bug shows as a 500 and a log line, never as a response missing its policy or carrying a second framing. +* A compromised worker cannot split a response to a remote server with its own `Content-Length`. + +### Negative Consequences + +* A route that today relies on an invalid header being dropped now fails. None does: no handler sets a framing header, + and every runtime header goes through `append_header_if_missing`, which validates first. + +## Pros and Cons of the Options + +### Drop invalid headers + +* Good, because a response still goes out. +* Bad, because what goes out lacks the header the handler meant to send, and nobody is told. + +### Repair + +* Good, because a response still goes out. +* Bad, because a repaired `Location` sends the browser somewhere the handler did not choose. + +## Links + +* Refines [ADR-0180](0180-the-outbound-client-refuses-invalid-header-fields.md) diff --git a/docs/adr/0768-the-oauth-module-is-pure-and-carries-the-wire-error-beside-core-error.md b/docs/adr/0768-the-oauth-module-is-pure-and-carries-the-wire-error-beside-core-error.md new file mode 100644 index 000000000..3480c660d --- /dev/null +++ b/docs/adr/0768-the-oauth-module-is-pure-and-carries-the-wire-error-beside-core-error.md @@ -0,0 +1,53 @@ +# The `oauth` module is pure, and carries the wire error beside `core::Error` + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-15 + +## Context and Problem Statement + +The OAuth 2.0 API ([ADR-0812](0812-the-oauth-2-0-api-is-built-into-the-homeserver.md)) needs PKCE, a scope parser, +redirect URI and client metadata validation and a page renderer. Every input is attacker-chosen, some are secrets, +and every refusal must name an OAuth `error` code (`invalid_scope`, `invalid_redirect_uri`, ...) as well as a +description. The coding rules return `std::expected` (spelt `std::variant` while the toolchain cannot +build ``), and `src/core/AGENTS.md` forbids error enums of a module's own. Where do these functions live, +and how does a refusal carry its wire code? + +## Considered Options + +* A module `oauth` of pure functions; a refusal is `OAuthRefusal`, a struct of the wire code string and a + `core::Error`. +* The same functions in `src/homeserver/`, beside the handlers. +* An `enum class OAuthError` as the error alternative. + +## Decision Outcome + +Chosen option: "a pure `oauth` module with `OAuthRefusal`". The module holds no state, does no I/O and logs nothing, +so every function can be unit-tested and fuzzed alone, and no secret can reach a log from it. A refusal is +`std::variant`; `OAuthRefusal::error_code` is one of the constants in `OAuthErrorCodes.hpp`, and +`OAuthRefusal::error` is a `core::Error` whose message is fixed text, safe to send as `error_description`. This is +the shape `federation::PublicRoomsRefusal` already uses for a Matrix `errcode`. A function with nothing to say but +"no" returns `bool` or `std::optional`. + +PKCE accepts only `S256`. A challenge must be the one canonical 43-character encoding of a 32-byte digest, so a +challenge no verifier can match is refused when the authorisation request arrives, not when the code is redeemed. + +### Positive Consequences + +* Handlers map a refusal to a response without a table: the code is already the wire value. +* The module links only `core`, `crypto`, `canonicaljson` and `auth`, and its fuzz targets need nothing else. + +### Negative Consequences + +* `error_code` is a string, so a misspelt code is not a compile error; use the constants. + +## Pros and Cons of the Options + +### The functions in `src/homeserver/` + +* Bad, because `homeserver` links everything, so the validators could not be fuzzed or tested in isolation. + +### An error enum + +* Bad, because `src/core/AGENTS.md` forbids module error enums, and the enum would still need a table to its wire + string. diff --git a/docs/adr/0769-an-oauth-scope-needs-the-api-token-and-exactly-one-device-token-of-ten-or-more-unreserved-characters.md b/docs/adr/0769-an-oauth-scope-needs-the-api-token-and-exactly-one-device-token-of-ten-or-more-unreserved-characters.md new file mode 100644 index 000000000..cdcf3e599 --- /dev/null +++ b/docs/adr/0769-an-oauth-scope-needs-the-api-token-and-exactly-one-device-token-of-ten-or-more-unreserved-characters.md @@ -0,0 +1,38 @@ +# An OAuth scope needs the API token and exactly one device token of ten or more unreserved characters + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-15 + +## Context and Problem Statement + +The spec ("Scope") defines `urn:matrix:client:api:*` and `urn:matrix:client:device:`, requires exactly +one device token in the login flow, lets the client choose the device ID, and lets the server refuse a device ID +that is shorter than ten characters or holds characters outside RFC 3986's unreserved set. It does not say what a +scope without the API token, with the same device token twice, or with unknown tokens means. + +## Considered Options + +* Strict: refuse a scope without the API token, with no device token or more than one (even the same one twice), + with a device ID outside `auth::device_id_is_valid`, shorter than ten or holding non-unreserved characters, and + with any byte outside RFC 6749's scope-token set or any spacing but single spaces; drop unknown tokens; know only + the stable token forms. +* Lenient: collapse repeated device tokens, accept any device ID the legacy API accepts, and also read the + `org.matrix.msc2967` forms. + +## Decision Outcome + +Chosen option: "Strict". The granted scope is rebuilt in canonical order +(`urn:matrix:client:api:* urn:matrix:client:device:`) from what was read, so tokens this server does not know +are never stored or echoed. The scope is capped at 2048 bytes and 32 tokens. + +### Positive Consequences + +* A device ID from the OAuth API is always safe as a path segment, a key ID suffix and a scope token, and long enough + that two devices of one user do not collide by chance. +* Two device tokens can never leave the server and the client disagreeing about which device was allocated. + +### Negative Consequences + +* A client that uses only the unstable MSC2967 forms, or a short device ID, cannot log in. Element X uses the stable + forms and a ten-character ID (`docs/todos/oauth-2-0-api.md`, "What Element X needs"). diff --git a/docs/adr/0770-oauth-addresses-are-read-by-a-strict-reader-of-our-own-and-matched-byte-for-byte.md b/docs/adr/0770-oauth-addresses-are-read-by-a-strict-reader-of-our-own-and-matched-byte-for-byte.md new file mode 100644 index 000000000..5acd4bfe4 --- /dev/null +++ b/docs/adr/0770-oauth-addresses-are-read-by-a-strict-reader-of-our-own-and-matched-byte-for-byte.md @@ -0,0 +1,55 @@ +# OAuth addresses are read by a strict reader of our own and matched byte for byte + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-15 + +## Context and Problem Statement + +A redirect URI decides where an authorisation code is sent; the spec calls its validation critical and requires +exact matching against the registered value, except that a native loopback URI registered without a port matches any +port. Client URIs, terms and policy links reach pages and headers. The server already reads URLs with +`http::parse_outbound_url`, which canonicalises through libcurl and accepts only `http` and `https`. How are these +addresses read? + +## Considered Options + +* A reader in `oauth` (`ParsedUri::read`) for a strict subset of RFC 3986 that keeps the bytes as given. +* `http::parse_outbound_url`. +* RFC 3986 normalisation before comparison (case of scheme and host, default ports, percent-encoding). + +## Decision Outcome + +Chosen option: "a strict reader of our own". It accepts 1 to 2048 bytes of printable ASCII; a scheme of RFC 3986 +characters; an optional authority with no userinfo, a host of LDH labels (no empty label, so no trailing dot, and no +`%`) or a bracketed IPv6 literal, and a port of 1 to 65535 with no leading zero; a path and query of `pchar` with +valid `%XX`. It refuses every fragment, a bare `#` included, and every `\`, quote, angle bracket and other byte +RFC 3986 does not allow raw. Nothing is decoded or normalised. + +Matching is byte for byte: `https://APP.example.com/cb` does not match `https://app.example.com/cb`, and an explicit +`:443` does not match its absence. `http` and `https` must be written in lower case wherever this module tests for +them; a private-use scheme is compared with the reversed client host in ASCII lower case, as the spec's rule is about +the name, not its spelling. Only a native client's loopback URI (`http`, host exactly `localhost`, `127.0.0.1` or +`[::1]`, no port at registration) matches the same bytes with `:` after the host. + +### Positive Consequences + +* No two spellings of one URI exist, so no check can pass on one spelling while the browser follows another. +* What the reader accepts is safe in a `Content-Security-Policy` source and, escaped, in an `href`. + +### Negative Consequences + +* A client must send its redirect URI exactly as registered; a client that changes the case of its host, or adds a + default port, is refused. +* Internationalised hosts must be sent in their ASCII (`xn--`) form. + +## Pros and Cons of the Options + +### `http::parse_outbound_url` + +* Bad, because it rewrites the URI through libcurl, so the value checked is not the value compared or sent. +* Bad, because it refuses the private-use schemes native clients need. + +### Normalisation + +* Bad, because every normalisation step is a place where the server and the browser can disagree. 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 new file mode 100644 index 000000000..31044903a --- /dev/null +++ b/docs/adr/0771-oauth-client-metadata-rules-and-its-canonical-form.md @@ -0,0 +1,59 @@ +# OAuth client metadata rules, and its canonical form + +* Status: accepted +* 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 +`native` must be supported, `none` must be supported, unknown grant and response types must be ignored, redirect URIs +must be validated) and leaves the rest to the server. Phase 4 derives the client ID from the accepted metadata +(proposal P2 in `docs/todos/oauth-2-0-api.md`), so the same metadata must always give the same bytes. + +## Decision Outcome + +The owner decided these rules on 2026-11-15; `ClientMetadata::validate` applies them: + +* `client_uri` is required: `https` in lower case, no userinfo, no fragment, and a host that is a DNS name of at least + two labels: not an IP literal (no brackets, no all-digit last label), not `localhost` and not under `.localhost`. + It is compared in ASCII lower case. +* `application_type` is `web` (also when omitted) or `native`. +* `redirect_uris` is an array of at most 16 strings, each checked by the redirect URI rules + ([ADR-0770](0770-oauth-addresses-are-read-by-a-strict-reader-of-our-own-and-matched-byte-for-byte.md)); a failure is + `invalid_redirect_uri`. Duplicates collapse and the list is sorted. +* `grant_types` defaults to `["authorization_code"]`; `authorization_code`, `refresh_token` and + `urn:ietf:params:oauth:grant-type:device_code` are known, others ignored, duplicates collapse. A list with no known + value is refused, since such a client could do nothing. +* `response_types` defaults to `["code"]`; `code` is known. With `authorization_code`, `code` and a redirect URI are + required. +* `token_endpoint_auth_method` is omitted or `none`: every client is public. +* `client_name` is 1 to 128 bytes of UTF-8 with no control character. The line and paragraph separators and the + bidirectional formatting characters (U+061C, U+200E, U+200F, U+202A to U+202E, U+2066 to U+2069) count as control + characters, because they can make one name display as another on the consent page. Text is refused, never + stripped. +* `policy_uri` and `tos_uri` are `https` on the client URI's host or a subdomain, with no userinfo or fragment. +* `logo_uri`, localised keys (`name#lang`) and unknown keys are ignored and never registered: logos are never + fetched ([ADR-0815](0815-the-authentication-pages-are-built-into-the-binary-without-javascript.md)), and one + language is shown. +* A known key of the wrong JSON type, a repeated key, or more than 128 members is `invalid_client_metadata`. + +The canonical form is the canonical JSON of the registration response's object without `client_id`: every registered +member, `token_endpoint_auth_method: "none"` included, lists in their fixed order. It does not depend on key order, +duplicate values or ignored members. + +### Positive Consequences + +* Identical registrations from every install of a client share one row. +* Nothing a client sends reaches a page or the canonical form unless a rule above accepted it. + +### Negative Consequences + +* A confidential client, or one with only an IP-literal or `localhost` client URI, cannot register. +* A client name in a script that needs a bidirectional mark to display correctly is refused. 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 new file mode 100644 index 000000000..a7efbb89b --- /dev/null +++ b/docs/adr/0772-page-text-is-escaped-by-type-and-the-page-policy-names-only-a-validated-redirect-origin.md @@ -0,0 +1,60 @@ +# Page text is escaped by type, and the page policy names only a validated redirect origin + +* Status: accepted +* 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-0815](0815-the-authentication-pages-are-built-into-the-binary-without-javascript.md) requires that text reaches a +page only through the renderer's escaping. A rule that relies on every caller remembering to escape fails once. +Chromium also applies the `form-action` directive to the redirect that follows a form post, so the consent page's +policy must allow the client's redirect target, which comes from the request. + +## Considered Options + +* Types: `HtmlText` can be made only by `HtmlText::escape` or from an `HtmlLiteral`, whose constructor is `consteval` + and refuses `& < > " '`; names, button values and `autocomplete` tokens are `HtmlName`, and a form action is a + `PagePath`, both `consteval`. Page parts accept nothing else. +* A renderer that escapes every `std::string` it is given. +* Template text with placeholders. + +## Decision Outcome + +Chosen option: "Types". A page part cannot be given a `std::string`, so unescaped text does not compile. Escaping +replaces `& < > " '` and refuses text that is empty, longer than 4096 bytes, invalid UTF-8, or holds a control or +bidirectional formatting character; the caller chooses what to show instead. A detail value is wrapped in ``. +A link is written only for an `https` URL that `ParsedUri::read` accepts. A form has one or two submit buttons with +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` (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 `.`. + +### Positive Consequences + +* Forgetting to escape is a compile error, not a vulnerability. +* A hostile redirect URI cannot add a directive or a second source to the policy. + +### Negative Consequences + +* A page cannot show text with a bidirectional mark, or any text over 4096 bytes. +* Fixed text with an apostrophe or ampersand must be written without one, or escaped at run time. + +## Pros and Cons of the Options + +### A renderer that escapes every string + +* Bad, because a string that was already HTML (a fragment built elsewhere) would be escaped twice, and the fix is a + "raw" overload that brings the bug back. + +### Templates + +* Bad, because a placeholder in an attribute, a URL and element content each needs a different escape, and nothing + checks that the right one was used. 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..9ff0bfce1 --- /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-0816](0816-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/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..6e7fd5ce2 --- /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,75 @@ +# 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 + +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 +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..c61eeb6d0 --- /dev/null +++ b/docs/adr/0777-an-oauth-client-s-last-use-is-written-at-most-once-a-day.md @@ -0,0 +1,69 @@ +# 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 + +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 +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 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 + +* 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/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..7615ab25c --- /dev/null +++ b/docs/adr/0779-an-oauth-client-id-is-a-keyed-hash-of-the-accepted-metadata.md @@ -0,0 +1,69 @@ +# 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 + +Amended 2026-11-16: the client ID key is no longer cached in `TokenHmacKeys`. Each client registration derives it from +the master key file (`crypto::derive_oauth_client_id_key_from_file`: one open, then the bytes from that open) and drops +it when the ID is made. Every cached key is a locked page held for the life of the process, and locked memory is a +per-process budget (`RLIMIT_MEMLOCK`, 64 KiB by default on FreeBSD, 16 pages). A standing page for a feature that may be +off pushed the server over that budget on FreeBSD, so the registration token file could no longer be read into locked +memory and every `POST /register` was refused. Registration is rare and in the `auth_sensitive` rate tier, so a file +read per registration costs little; do not cache the key again, and do not add a key to `TokenHmacKeys` for any purpose +but hashing access tokens. + +## 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 derived from one read of the master key file for each registration (amended above). 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..7e8bed1a8 --- /dev/null +++ b/docs/adr/0780-oauth-registrations-are-capped-and-idle-clients-are-evicted-least-recently-used-first.md @@ -0,0 +1,61 @@ +# 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) + +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 +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/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/0787-every-oauth-authorisation-asks-for-the-password-and-no-browser-session-is-kept.md b/docs/adr/0787-every-oauth-authorisation-asks-for-the-password-and-no-browser-session-is-kept.md new file mode 100644 index 000000000..bc18418b5 --- /dev/null +++ b/docs/adr/0787-every-oauth-authorisation-asks-for-the-password-and-no-browser-session-is-kept.md @@ -0,0 +1,64 @@ +# Every OAuth authorisation asks for the password, and no browser session is kept + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 5b of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md), proposal P6 + +## Context and Problem Statement + +Under the OAuth 2.0 API a client never sees the password: it sends the browser to `GET /_merovingian/oauth2/authorize`, +and this server's pages sign the user in and ask for consent. Most authorisation servers keep a signed-in browser +session, so a second authorisation from the same browser skips the password and only asks for consent (or nothing, +with `prompt=none`). Should this server keep one? + +## Decision Drivers + +* A cookie that stands for a signed-in account is a credential: stolen, it signs an attacker's client in. +* An "already signed in" path is a second way into the consent page, and the one most likely to be got wrong. +* Clients ask rarely: a login, an account creation, a re-login after a revoked session. + +## Considered Options + +* No browser session: every authorisation asks for the password (or creates the account) +* A signed-in browser session in a cookie, for a fixed time, that skips the password + +## Decision Outcome + +Chosen option: no browser session. + +* Every authorisation request shows the login or registration form, and only a password verified (or an account + created) for that one pending authorisation lets its consent page be approved. `PendingAuthorisationStore::record_user` + records the user on that entry only; nothing records it for the browser. +* The one cookie the endpoint sets, `__Host-mv-oauth`, binds a pending authorisation to its browser for ten minutes + ([ADR-0788](0788-the-oauth-browser-binding-is-one-host-cookie-and-the-pending-identifier-is-the-form-token.md)). It + never stands for an account. +* `prompt=none`, which asks for an answer without any page, is refused with `login_required`, as OpenID Connect Core + 1.0 section 3.1.2.6 says a server that would need to show a page answers. `prompt=login`, `consent` and + `select_account` show the login form, which they always would. + +### Positive Consequences + +* No standing cookie to steal, and nothing to sign out of in the browser. +* The consent page is reached only through `verify_password_login` or `create_local_account`, so the failed-login + throttle and the Argon2id budget cover every authorisation. + +### Negative Consequences + +* A user who signs in from several clients types the password each time. +* A client that relies on `prompt=none` for a silent re-authorisation gets `login_required` and must show the page. + +## Pros and Cons of the Options + +### A signed-in browser session + +* Good, because a second login from the same browser is one click. +* Bad, because the cookie is a bearer credential for the account, and a forged consent post needs only it. +* Bad, because it adds a sign-out for the browser, an expiry and a revocation to get right. + +## Links + +* Implements plan proposal P6 for the authorisation pages; the account pages (phase 8) keep their own 15-minute session +* 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/0788-the-oauth-browser-binding-is-one-host-cookie-and-the-pending-identifier-is-the-form-token.md b/docs/adr/0788-the-oauth-browser-binding-is-one-host-cookie-and-the-pending-identifier-is-the-form-token.md new file mode 100644 index 000000000..345090ae2 --- /dev/null +++ b/docs/adr/0788-the-oauth-browser-binding-is-one-host-cookie-and-the-pending-identifier-is-the-form-token.md @@ -0,0 +1,75 @@ +# The OAuth browser binding is one `__Host-` cookie, and the pending identifier is the form token + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 5b of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md) + +## Context and Problem Statement + +A pending authorisation (ADR-0782) is held under a random identifier that the page carries in a hidden form field. +Anyone who learns that identifier must not be able to finish the login from another browser, and another site must +not be able to post the forms (login CSRF, a forged consent). The plan asks for a `__Host-` cookie and "a token checked +against the cookie" on each form. How many cookies, which value, and what is the form token? + +## Decision Drivers + +* Two tabs, or a client that starts a second login before the first ends, must not end each other's login. +* No value that grants anything may be readable by script or sent to another host. +* Every form post needs a check another site cannot pass. + +## Considered Options + +* One cookie, `__Host-mv-oauth`, whose value is reused while well-formed; the pending identifier is the per-form token; + every post is also held to `Origin` and `Sec-Fetch-Site` +* One cookie per pending authorisation, named after it +* A separate random form token per page, kept in the entry beside the identifier + +## Decision Outcome + +Chosen option: one cookie reused, the pending identifier as the form token, and the `Origin` check. + +* `GET /_merovingian/oauth2/authorize` sets `__Host-mv-oauth` with `core::host_cookie`: `Secure`, `HttpOnly`, `Path=/`, + no `Domain`, `SameSite=Lax` (the client opens the page with a top-level navigation from another site, which `Strict` + would strip), `Max-Age=600`, the lifetime of a pending authorisation. Its value is the browser token the entry is bound + to (`PendingAuthorisationStore::create`), kept by the store only as a hash. +* A request that already carries a well-formed value (64 lower-case hex digits, what `make_oauth_secret` mints) reuses + it, so every pending authorisation of one browser shares the one token and a second tab does not replace the first + tab's cookie. Anything else (absent, repeated, malformed) gets a fresh 32-byte value from `make_oauth_secret`. +* Every `POST` must name both the hidden `pending` field and the cookie, and the store answers a wrong pairing exactly as + an unknown identifier: a 400 page saying the sign-in expired, never a redirect. The identifier is 256 random bits, + unknown to another site, so it is the per-form token; a second token would be compared against the same entry and + add nothing. +* Before anything else a `POST` must pass `oauth::form_post_origin_is_accepted` with its `Origin` and `Sec-Fetch-Site` + (ADR-0784), else a 403 page. A header sent twice counts as absent. + +### Positive Consequences + +* A leaked pending identifier (a screenshot, a log a proxy kept) is useless without the browser's cookie, and the + cookie without the identifier names nothing. +* A cross-site post fails on `Origin` even when the browser sends the `Lax` cookie with a top-level `POST`. + +### Negative Consequences + +* A browser that strips `Origin` from same-origin posts, or refuses cookies, cannot complete a login. +* All pending authorisations of a browser share one token, so a stolen cookie value plus one identifier is enough; both + are needed in every case. + +## Pros and Cons of the Options + +### One cookie per pending authorisation + +* Good, because each entry has its own secret. +* Bad, because the cookie count grows with abandoned logins and the name itself must carry the identifier. + +### A separate form token + +* Bad, because it is a second secret compared against the same entry the identifier already names, and must be kept + and wiped beside it. + +## Links + +* Refines the plan's "The authorisation flow", step 2 +* Builds on [ADR-0782](0782-pending-authorisations-and-authorization-codes-are-in-memory-hashed-bounded-and-never-evicted.md) + and [ADR-0784](0784-oauth-pages-use-a-same-origin-referrer-policy-and-a-form-post-must-name-this-server-s-origin.md) diff --git a/docs/adr/0789-response-mode-query-is-accepted-for-an-https-redirect-uri.md b/docs/adr/0789-response-mode-query-is-accepted-for-an-https-redirect-uri.md new file mode 100644 index 000000000..79e086c86 --- /dev/null +++ b/docs/adr/0789-response-mode-query-is-accepted-for-an-https-redirect-uri.md @@ -0,0 +1,57 @@ +# `response_mode=query` is accepted for an `https` redirect URI + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 5b of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md) + +## Context and Problem Statement + +Spec v1.19 "Authorisation code grant" says homeservers and clients MUST "use the `fragment` response mode ... for +clients with an HTTPS redirect URI", and "Login flow" says clients SHOULD use `fragment` when the redirect URI is an +`https` URI with a remote host, so the code does not reach the web server behind it. Should the authorisation endpoint +refuse `response_mode=query` (or an absent `response_mode`, which RFC 6749 makes `query`) when the redirect URI is +`https`? + +## Decision Drivers + +* The MUST is written for "homeservers and clients" together: it is the client that chooses the mode. +* Element X on iOS registers a claimed `https` redirect URI, and which mode it sends was not verified (the plan's open + items under "What Element X needs"). Refusing would lock it out until a release of the client. +* The code is useless without the PKCE verifier, which only the client holds. + +## Considered Options + +* Accept `query` and `fragment` for every redirect URI; an absent `response_mode` is `query` +* Refuse `query` (and an absent mode) for an `https` redirect URI with `invalid_request` +* Answer in the fragment for an `https` redirect URI whatever the client asked + +## Decision Outcome + +Chosen option: accept both modes for every redirect URI, and read an absent `response_mode` as `query`. Only another +value is refused, with `invalid_request` in the query. + +### Positive Consequences + +* A client that sends `query` for a claimed `https` link still logs in. + +### Negative Consequences + +* For such a client the code reaches the server behind the redirect URI in its query, and its logs. PKCE keeps it from + being redeemed by anyone else, and it lives 60 seconds. + +## Pros and Cons of the Options + +### Refuse `query` for an `https` redirect URI + +* Good, because it holds clients to the spec's rule. +* Bad, because a client this server must serve may be locked out with no way for the user to recover. + +### Answer in the fragment whatever was asked + +* Bad, because a client reading the query would not find its code: repairing a request is what the module rules forbid. + +## Links + +* Revisit after phase 11 tests the flow with the real Element X clients diff --git a/docs/adr/0790-an-oauth-approval-is-judged-again-and-audited-and-its-redirect-sends-no-referrer.md b/docs/adr/0790-an-oauth-approval-is-judged-again-and-audited-and-its-redirect-sends-no-referrer.md new file mode 100644 index 000000000..b1e473478 --- /dev/null +++ b/docs/adr/0790-an-oauth-approval-is-judged-again-and-audited-and-its-redirect-sends-no-referrer.md @@ -0,0 +1,53 @@ +# An OAuth approval is judged again and audited, and its redirect sends no referrer + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 5b of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md) + +## Context and Problem Statement + +`approve` on the consent page turns a signed-in user into an authorization code. Between the password and the +approval the account can be deactivated or locked, and the approval itself is the moment the user hands a device to +an application. What does `approve` check, what does it record, and what does the redirect to the client carry? + +## Decision Drivers + +* The password check releases `runtime.mutex`; the consent page can be left open for minutes. +* `auth.login` is a durable audit row; an approval grants the same access through another door. +* The authorisation request's address is not the client's business once the browser leaves this server. + +## Considered Options + +* Trust the user recorded at sign-in, log only, and let the browser's referrer policy apply. +* Judge the account again at `approve`, audit the grant, and send `Referrer-Policy: no-referrer` on the redirect. + +## Decision Outcome + +Chosen option: the second. + +* `approve` consumes the pending authorisation, then asks `account_sign_in_gate` again, the gate + `verify_password_login` uses. An account that may no longer sign in gets `access_denied` at the client, never a + code. The gate is the same function, so the two cannot disagree. +* `oauth.authorization.granted` is a durable audit row (category `auth`, actor the user, target the client ID, reason + the device ID), as `auth.login` is. `oauth.authorization.denied` is audited the same way only when a user had signed + in: a denial before the password can be sent by anyone and would let a stranger fill the audit log. Refusals of the + request are diagnostic log lines only, bounded by the `auth_sensitive` rate limit. +* Every redirect to the client carries `Cache-Control: no-store` and `Referrer-Policy: no-referrer`. A redirect is + not a page, so it does not carry the pages' headers (`same-origin`, ADR-0784); `no-referrer` is stricter and keeps + this server's address out of the client's page. + +### Positive Consequences + +* A deactivation between sign-in and approval issues no code. +* Every grant can be found in the audit log, as every password login can. + +### Negative Consequences + +* One more audit row per sign-in through the pages. + +## Links + +* Builds on [ADR-0783](0783-login-verification-and-account-creation-are-one-function-each-shared-by-the-matrix-routes-and-the-oauth-pages.md) + and [ADR-0784](0784-oauth-pages-use-a-same-origin-referrer-policy-and-a-form-post-must-name-this-server-s-origin.md) 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..9e1f97e3e --- /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,49 @@ +# 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) + +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 +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/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..5842f4929 --- /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,83 @@ +# 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`. + +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. + +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 +`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/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..64e6bab8d --- /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,82 @@ +# 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). + +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 +`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/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..16b806298 --- /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-0813](0813-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/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..b73baf74d --- /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,87 @@ +# 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. + +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` +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/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..ec211672b --- /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,79 @@ +# 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`). + +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 +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/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/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/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/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/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/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/0812-the-oauth-2-0-api-is-built-into-the-homeserver.md b/docs/adr/0812-the-oauth-2-0-api-is-built-into-the-homeserver.md new file mode 100644 index 000000000..09fb5983b --- /dev/null +++ b/docs/adr/0812-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-0815](0815-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-0813](0813-the-legacy-authentication-api-stays-on-by-default-and-a-config-key-turns-it-off.md), + [ADR-0814](0814-the-registration-page-applies-the-legacy-registration-settings.md), + [ADR-0815](0815-the-authentication-pages-are-built-into-the-binary-without-javascript.md) and + [ADR-0816](0816-server-oauth-replaces-server-oidc-and-the-old-keys-are-refused.md) diff --git a/docs/adr/0813-the-legacy-authentication-api-stays-on-by-default-and-a-config-key-turns-it-off.md b/docs/adr/0813-the-legacy-authentication-api-stays-on-by-default-and-a-config-key-turns-it-off.md new file mode 100644 index 000000000..42f2b9a17 --- /dev/null +++ b/docs/adr/0813-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-0812](0812-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/0814-the-registration-page-applies-the-legacy-registration-settings.md b/docs/adr/0814-the-registration-page-applies-the-legacy-registration-settings.md new file mode 100644 index 000000000..a44f2daa1 --- /dev/null +++ b/docs/adr/0814-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-0813](0813-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/0815-the-authentication-pages-are-built-into-the-binary-without-javascript.md b/docs/adr/0815-the-authentication-pages-are-built-into-the-binary-without-javascript.md new file mode 100644 index 000000000..07ebf54c0 --- /dev/null +++ b/docs/adr/0815-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-0812](0812-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 `")"); + 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. +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, std::nullopt).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, 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") + { + 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_authorization_code_store.cpp b/tests/unit/test_oauth_authorization_code_store.cpp new file mode 100644 index 000000000..c157dbb2d --- /dev/null +++ b/tests/unit/test_oauth_authorization_code_store.cpp @@ -0,0 +1,352 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +// Plan P5 (ADR-0782): the in-memory authorisation codes an approval mints and the token endpoint redeems. Hashed, 60 +// seconds, single use, a replay recognised until the code's own expiry, bounded, never evicting a live code. + +#include "merovingian/homeserver/AuthorizationCodeRedemption.hpp" +#include "merovingian/homeserver/AuthorizationCodeStore.hpp" +#include "merovingian/homeserver/AuthorizationGrant.hpp" + +#include +#include + +#include +#include +#include +#include +#include +#include + +namespace +{ + +using merovingian::homeserver::AuthorizationCodeRedemption; +using merovingian::homeserver::AuthorizationCodeStore; +using merovingian::homeserver::AuthorizationGrant; +using Outcome = merovingian::homeserver::AuthorizationCodeRedemption::Outcome; + +constexpr auto start_ms = std::uint64_t{5'000'000U}; + +[[nodiscard]] auto grant_for(std::string client_id, std::string device_id) -> AuthorizationGrant +{ + return {std::move(client_id), + "https://app.example.org/callback", + "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", + "@alice:example.org", + device_id, + "urn:matrix:client:api:* urn:matrix:client:device:" + device_id}; +} + +[[nodiscard]] auto code_of(std::variant const& issued) -> std::string +{ + REQUIRE(std::holds_alternative(issued)); + return std::get(issued); +} + +} // namespace + +SCENARIO("An authorisation code is redeemed once, and a second presentation is recognised as a replay", + "[oauth][oauth-code]") +{ + REQUIRE(sodium_init() >= 0); + GIVEN("a store holding one code") + { + auto store = AuthorizationCodeStore{}; + auto const code = code_of(store.issue(grant_for("client-a", "DEVICEA"), start_ms)); + + WHEN("it is redeemed twice") + { + auto const first = store.redeem(code, start_ms + 1U); + auto const second = store.redeem(code, start_ms + 2U); + + THEN("the first is fresh with the whole grant") + { + REQUIRE(first.outcome == Outcome::fresh); + CHECK(first.grant.client_id == "client-a"); + CHECK(first.grant.redirect_uri == "https://app.example.org/callback"); + CHECK(first.grant.code_challenge == "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"); + CHECK(first.grant.user_id == "@alice:example.org"); + CHECK(first.grant.device_id == "DEVICEA"); + CHECK(first.grant.scope == "urn:matrix:client:api:* urn:matrix:client:device:DEVICEA"); + } + + THEN("the second is a replay naming the session the first was for, without the grant") + { + REQUIRE(second.outcome == Outcome::replayed); + CHECK(second.user_id == "@alice:example.org"); + CHECK(second.device_id == "DEVICEA"); + CHECK(second.grant.client_id.empty()); + CHECK(second.grant.code_challenge.empty()); + } + } + + WHEN("an unknown code and the empty code are redeemed") + { + auto const unknown = store.redeem(std::string(64U, 'f'), start_ms + 1U); + auto const empty = store.redeem("", start_ms + 1U); + + THEN("both are unknown and the real code is still fresh") + { + CHECK(unknown.outcome == Outcome::unknown); + CHECK(unknown.user_id.empty()); + CHECK(empty.outcome == Outcome::unknown); + CHECK(store.redeem(code, start_ms + 2U).outcome == Outcome::fresh); + } + } + + WHEN("the code is looked at") + { + THEN("it is 64 hex digits") + { + REQUIRE(code.size() == 64U); + CHECK(code.find_first_not_of("0123456789abcdef") == std::string::npos); + } + } + } +} + +SCENARIO("An authorisation code lives 60 seconds, to the millisecond, and so does its replay record", + "[oauth][oauth-code]") +{ + REQUIRE(sodium_init() >= 0); + GIVEN("a code issued at a known time") + { + auto store = AuthorizationCodeStore{}; + auto const code = code_of(store.issue(grant_for("client-a", "DEVICEA"), start_ms)); + auto const end_ms = start_ms + AuthorizationCodeStore::lifetime_ms; + + WHEN("it is redeemed one millisecond before its end") + { + auto const redeemed = store.redeem(code, end_ms - 1U); + + THEN("it is fresh") + { + CHECK(redeemed.outcome == Outcome::fresh); + } + } + + WHEN("it is redeemed at exactly its end") + { + auto const redeemed = store.redeem(code, end_ms); + + THEN("it is unknown and removed") + { + CHECK(redeemed.outcome == Outcome::unknown); + CHECK(store.size() == 0U); + } + } + + WHEN("it is redeemed, then presented again just before and at its end") + { + REQUIRE(store.redeem(code, start_ms + 1U).outcome == Outcome::fresh); + auto const late_replay = store.redeem(code, end_ms - 1U); + auto const after_end = store.redeem(code, end_ms); + + THEN("the replay is recognised until the code's own expiry and forgotten from then") + { + CHECK(late_replay.outcome == Outcome::replayed); + CHECK(after_end.outcome == Outcome::unknown); + CHECK(store.size() == 0U); + } + } + } +} + +SCENARIO("The authorisation codes are capped, purge expired codes first and never evict a live one", + "[oauth][oauth-code][cap]") +{ + REQUIRE(sodium_init() >= 0); + GIVEN("a store holding its cap of codes, the first already redeemed") + { + auto store = AuthorizationCodeStore{}; + auto first = std::string{}; + auto last = std::string{}; + for (auto index = std::size_t{0U}; index < AuthorizationCodeStore::max_codes; ++index) + { + last = code_of(store.issue(grant_for("client-" + std::to_string(index % 4U), "DEV"), start_ms + index)); + if (index == 0U) + { + first = last; + } + } + REQUIRE(store.redeem(first, start_ms + AuthorizationCodeStore::max_codes).outcome == Outcome::fresh); + + WHEN("another code is asked for while every code is live") + { + auto const refused = + store.issue(grant_for("client-new", "DEV"), start_ms + AuthorizationCodeStore::max_codes); + + THEN("it is refused, the redeemed code still counts and is still recognised, and the last code is fresh") + { + REQUIRE(std::holds_alternative(refused)); + CHECK(std::get(refused) == + AuthorizationCodeStore::Refusal::store_full); + CHECK(store.size() == AuthorizationCodeStore::max_codes); + CHECK(store.redeem(first, start_ms + AuthorizationCodeStore::max_codes).outcome == Outcome::replayed); + CHECK(store.redeem(last, start_ms + AuthorizationCodeStore::max_codes).outcome == Outcome::fresh); + } + } + + WHEN("the first code has expired and another is asked for") + { + auto const later = start_ms + AuthorizationCodeStore::lifetime_ms; + auto const issued = store.issue(grant_for("client-new", "DEV"), later); + + THEN("the expired code was purged to make room") + { + CHECK(std::holds_alternative(issued)); + CHECK(store.size() == AuthorizationCodeStore::max_codes); + CHECK(store.redeem(first, later).outcome == Outcome::unknown); + } + } + } +} + +SCENARIO("The unredeemed codes of a client are counted without a scan", "[oauth][oauth-code]") +{ + REQUIRE(sodium_init() >= 0); + GIVEN("two codes for one client, ten seconds apart, and one for another") + { + auto store = AuthorizationCodeStore{}; + auto const early = code_of(store.issue(grant_for("client-a", "DEV1"), start_ms)); + std::ignore = code_of(store.issue(grant_for("client-a", "DEV2"), start_ms + 10'000U)); + std::ignore = code_of(store.issue(grant_for("client-b", "DEV3"), start_ms)); + + WHEN("the earlier code is redeemed") + { + auto const before = store.unredeemed_count_for_client("client-a", start_ms + 1U); + REQUIRE(store.redeem(early, start_ms + 1U).outcome == Outcome::fresh); + auto const after = store.unredeemed_count_for_client("client-a", start_ms + 1U); + + THEN("the redeemed code no longer counts, though it is still held for replay detection") + { + CHECK(before == 2U); + CHECK(after == 1U); + CHECK(store.size() == 3U); + CHECK(store.unredeemed_count_for_client("client-b", start_ms + 1U) == 1U); + CHECK(store.unredeemed_count_for_client("client-c", start_ms + 1U) == 0U); + } + } + + WHEN("the codes expire") + { + auto const end_early = start_ms + AuthorizationCodeStore::lifetime_ms; + auto const end_late = end_early + 10'000U; + + THEN("the client holds a live code until its latest one ends") + { + CHECK(store.holds_unredeemed_code_for_client("client-a", end_early)); + CHECK(store.unredeemed_count_for_client("client-a", end_early) == 1U); + CHECK_FALSE(store.holds_unredeemed_code_for_client("client-a", end_late)); + CHECK(store.unredeemed_count_for_client("client-a", end_late) == 0U); + } + } + + WHEN("a client that holds no code is asked about") + { + auto const unknown_client = store.holds_unredeemed_code_for_client("client-c", start_ms + 1U); + + THEN("it holds none") + { + CHECK_FALSE(unknown_client); + } + } + } +} + +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_authorization_pages.cpp b/tests/unit/test_oauth_authorization_pages.cpp new file mode 100644 index 000000000..5259e6003 --- /dev/null +++ b/tests/unit/test_oauth_authorization_pages.cpp @@ -0,0 +1,466 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// The pages of the authorisation endpoint (oauth/AuthorizationPages.hpp, ADR-0815, ADR-0772): login, registration, +// 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 +#include + +namespace +{ + +using merovingian::oauth::AccountFormInput; +using merovingian::oauth::ConsentPageInput; +using merovingian::oauth::HtmlText; +using merovingian::oauth::ParsedUri; + +// Breaks out of an attribute and an element if it is not escaped. +constexpr auto markup = std::string_view{"\">&"}; +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, "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 + +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"); + } + } + } +} diff --git a/tests/unit/test_oauth_client_metadata.cpp b/tests/unit/test_oauth_client_metadata.cpp new file mode 100644 index 000000000..d72e679dc --- /dev/null +++ b/tests/unit/test_oauth_client_metadata.cpp @@ -0,0 +1,472 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// oauth::ClientMetadata (spec v1.19 Client-Server API "Client metadata", "Dynamic client registration flow", +// RFC 7591; ADR-0771). + +#include "merovingian/canonicaljson/Parser.hpp" +#include "merovingian/canonicaljson/Serializer.hpp" +#include "merovingian/canonicaljson/Value.hpp" +#include "merovingian/core/Error.hpp" +#include "merovingian/oauth/ApplicationType.hpp" +#include "merovingian/oauth/ClientMetadata.hpp" +#include "merovingian/oauth/OAuthErrorCodes.hpp" +#include "merovingian/oauth/OAuthRefusal.hpp" + +#include + +#include +#include +#include +#include +#include +#include +#include + +namespace +{ + +using merovingian::canonicaljson::Object; +using merovingian::canonicaljson::Value; +using merovingian::oauth::ClientMetadata; +using merovingian::oauth::OAuthRefusal; + +[[nodiscard]] auto parse(std::string_view json) -> Value +{ + auto parsed = merovingian::canonicaljson::parse_json(json); + REQUIRE(parsed.error == merovingian::canonicaljson::ParseError::none); + return std::move(parsed.value); +} + +[[nodiscard]] auto validate(std::string_view json) -> std::variant +{ + return ClientMetadata::validate(parse(json)); +} + +[[nodiscard]] auto refusal_code(std::variant const& result) -> std::string +{ + auto const* refusal = std::get_if(&result); + return refusal == nullptr ? std::string{} : refusal->error_code; +} + +[[nodiscard]] auto canonical(std::variant const& result) -> std::string +{ + auto const* metadata = std::get_if(&result); + REQUIRE(metadata != nullptr); + auto bytes = metadata->canonical_bytes(); + REQUIRE(std::holds_alternative(bytes)); + return std::get(std::move(bytes)); +} + +// The smallest valid web registration. +constexpr auto minimal_web = + std::string_view{R"({"client_uri":"https://example.com/","redirect_uris":["https://example.com/cb"]})"}; + +} // namespace + +SCENARIO("The spec's registration example registers what the spec's answer shows", "[oauth][metadata]") +{ + // Spec v1.19 Client-Server API, "Dynamic client registration flow": the example request and response. + GIVEN("the example registration request") + { + auto const 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" + })"}; + + WHEN("it is validated and serialised") + { + auto const result = validate(request); + + THEN("the localised values, the logo and the unknown grant type are not registered") + { + REQUIRE(canonical(result) == + R"({"application_type":"web","client_name":"My App","client_uri":"https://example.com/",)" + R"("grant_types":["authorization_code","refresh_token"],)" + R"("policy_uri":"https://example.com/policy.html",)" + R"("redirect_uris":["https://app.example.com/callback"],"response_types":["code"],)" + R"("token_endpoint_auth_method":"none","tos_uri":"https://example.com/tos.html"})"); + auto const& metadata = std::get(result); + REQUIRE(metadata.application_type() == merovingian::oauth::ApplicationType::web); + REQUIRE(metadata.has_grant_type("refresh_token")); + REQUIRE_FALSE(metadata.has_grant_type("urn:ietf:params:oauth:grant-type:token-exchange")); + } + } + } +} + +SCENARIO("Omitted members take the RFC 7591 defaults", "[oauth][metadata]") +{ + GIVEN("a registration with only client_uri and redirect_uris") + { + WHEN("it is validated") + { + auto const result = validate(minimal_web); + + THEN("it is a web client with the authorization_code grant, the code response type and auth method none") + { + auto const* metadata = std::get_if(&result); + REQUIRE(metadata != nullptr); + REQUIRE(metadata->application_type() == merovingian::oauth::ApplicationType::web); + REQUIRE(metadata->grant_types() == std::vector{"authorization_code"}); + REQUIRE(metadata->response_types() == std::vector{"code"}); + REQUIRE_FALSE(metadata->client_name().has_value()); + REQUIRE(canonical(result).find(R"("token_endpoint_auth_method":"none")") != std::string::npos); + } + } + } +} + +SCENARIO("The canonical bytes ignore key order, duplicate values and ignored members", "[oauth][metadata]") +{ + GIVEN("two requests for the same metadata written differently") + { + auto const first = std::string_view{R"({"client_uri":"https://example.com/","application_type":"native",)" + R"("redirect_uris":["com.example.app:/cb","http://127.0.0.1/cb"],)" + R"("grant_types":["refresh_token","authorization_code"]})"}; + auto const second = std::string_view{ + R"({"logo_uri":"https://example.com/l.png","grant_types":["authorization_code","x","refresh_token",)" + R"("authorization_code"],"redirect_uris":["http://127.0.0.1/cb","com.example.app:/cb",)" + R"("http://127.0.0.1/cb"],"client_name#de":"App","response_types":["code","token","code"],)" + R"("token_endpoint_auth_method":"none","unknown":{"deep":[1,2]},"application_type":"native",)" + R"("client_uri":"https://example.com/"})"}; + + WHEN("both are validated") + { + auto const a = canonical(validate(first)); + auto const b = canonical(validate(second)); + + THEN("the canonical bytes are identical") + { + REQUIRE(a == b); + REQUIRE(a == R"({"application_type":"native","client_uri":"https://example.com/",)" + R"("grant_types":["authorization_code","refresh_token"],)" + R"("redirect_uris":["com.example.app:/cb","http://127.0.0.1/cb"],)" + R"("response_types":["code"],"token_endpoint_auth_method":"none"})"); + } + } + } +} + +SCENARIO("A known member of the wrong JSON type is invalid_client_metadata", "[oauth][metadata][security]") +{ + GIVEN("registrations each giving one known member the wrong type") + { + auto const bodies = std::array{ + R"({"client_uri":1})", + R"({"client_uri":null})", + R"({"client_uri":"https://example.com/","redirect_uris":"https://example.com/cb"})", + R"({"client_uri":"https://example.com/","redirect_uris":[1]})", + R"({"client_uri":"https://example.com/","redirect_uris":["https://example.com/cb"],"application_type":["web"]})", + R"({"client_uri":"https://example.com/","redirect_uris":["https://example.com/cb"],"grant_types":"authorization_code"})", + R"({"client_uri":"https://example.com/","redirect_uris":["https://example.com/cb"],"grant_types":[true]})", + R"({"client_uri":"https://example.com/","redirect_uris":["https://example.com/cb"],"response_types":{}})", + R"({"client_uri":"https://example.com/","redirect_uris":["https://example.com/cb"],"token_endpoint_auth_method":0})", + R"({"client_uri":"https://example.com/","redirect_uris":["https://example.com/cb"],"client_name":5})", + R"({"client_uri":"https://example.com/","redirect_uris":["https://example.com/cb"],"policy_uri":false})", + R"({"client_uri":"https://example.com/","redirect_uris":["https://example.com/cb"],"tos_uri":[]})", + }; + + WHEN("each is validated") + { + THEN("each is refused with invalid_client_metadata") + { + for (auto const body : bodies) + { + INFO(body); + REQUIRE(refusal_code(validate(body)) == merovingian::oauth::error_invalid_client_metadata); + } + REQUIRE(refusal_code(validate("[]")) == merovingian::oauth::error_invalid_client_metadata); + REQUIRE(refusal_code(validate("{}")) == merovingian::oauth::error_invalid_client_metadata); + } + } + } +} + +SCENARIO("Unsupported application types and auth methods are refused", "[oauth][metadata]") +{ + GIVEN("a registration with application_type desktop, and one with client_secret_basic") + { + auto const desktop = std::string_view{ + R"({"client_uri":"https://example.com/","redirect_uris":["https://example.com/cb"],"application_type":"desktop"})"}; + auto const secret = + std::string_view{R"({"client_uri":"https://example.com/","redirect_uris":["https://example.com/cb"],)" + R"("token_endpoint_auth_method":"client_secret_basic"})"}; + + WHEN("each is validated") + { + THEN("each is invalid_client_metadata") + { + REQUIRE(refusal_code(validate(desktop)) == merovingian::oauth::error_invalid_client_metadata); + REQUIRE(refusal_code(validate(secret)) == merovingian::oauth::error_invalid_client_metadata); + } + } + } +} + +SCENARIO("A bad redirect URI is invalid_redirect_uri; too many is invalid_client_metadata", "[oauth][metadata]") +{ + GIVEN("a registration with an off-host redirect URI and one with 17 redirect URIs") + { + auto const off_host = std::string_view{ + R"({"client_uri":"https://example.com/","redirect_uris":["https://example.com/cb","https://app.com/cb"]})"}; + auto many = std::string{R"({"client_uri":"https://example.com/","redirect_uris":[)"}; + for (auto index = std::size_t{0U}; index < 17U; ++index) + { + many.append(index == 0U ? "" : ","); + many.append("\"https://example.com/cb" + std::to_string(index) + "\""); + } + many.append("]}"); + + WHEN("each is validated") + { + THEN("the error codes are as stated, and 16 URIs are accepted") + { + REQUIRE(refusal_code(validate(off_host)) == merovingian::oauth::error_invalid_redirect_uri); + REQUIRE(refusal_code(validate(many)) == merovingian::oauth::error_invalid_client_metadata); + auto sixteen = std::string{R"({"client_uri":"https://example.com/","redirect_uris":[)"}; + for (auto index = std::size_t{0U}; index < 16U; ++index) + { + sixteen.append(index == 0U ? "" : ","); + sixteen.append("\"https://example.com/cb" + std::to_string(index) + "\""); + } + sixteen.append("]}"); + REQUIRE(refusal_code(validate(sixteen)).empty()); + } + } + } +} + +SCENARIO("The authorization_code grant needs the code response type and a redirect URI", "[oauth][metadata]") +{ + GIVEN("an authorization_code client with no redirect URI, and one whose only response type is token") + { + auto const no_redirect = std::string_view{R"({"client_uri":"https://example.com/"})"}; + auto const empty_redirects = std::string_view{R"({"client_uri":"https://example.com/","redirect_uris":[]})"}; + auto const token_only = std::string_view{ + R"({"client_uri":"https://example.com/","redirect_uris":["https://example.com/cb"],"response_types":["token"]})"}; + + WHEN("each is validated") + { + THEN("each is invalid_client_metadata") + { + REQUIRE(refusal_code(validate(no_redirect)) == merovingian::oauth::error_invalid_client_metadata); + REQUIRE(refusal_code(validate(empty_redirects)) == merovingian::oauth::error_invalid_client_metadata); + REQUIRE(refusal_code(validate(token_only)) == merovingian::oauth::error_invalid_client_metadata); + } + } + } +} + +SCENARIO("A device-grant client needs no redirect URI, and a client with no known grant is refused", + "[oauth][metadata]") +{ + GIVEN("a device_code client without redirect URIs, and a client naming only an unknown grant") + { + auto const device = + std::string_view{R"({"client_uri":"https://example.com/","application_type":"native",)" + R"("grant_types":["urn:ietf:params:oauth:grant-type:device_code","refresh_token"]})"}; + auto const unknown_only = std::string_view{ + R"({"client_uri":"https://example.com/","redirect_uris":["https://example.com/cb"],"grant_types":["implicit"]})"}; + + WHEN("each is validated") + { + auto const device_result = validate(device); + + THEN("the device client is registered and the other refused") + { + auto const* metadata = std::get_if(&device_result); + REQUIRE(metadata != nullptr); + REQUIRE(metadata->grant_types() == std::vector{ + "refresh_token", + "urn:ietf:params:oauth:grant-type:device_code", + }); + REQUIRE(metadata->redirect_uris().empty()); + REQUIRE(refusal_code(validate(unknown_only)) == merovingian::oauth::error_invalid_client_metadata); + } + } + } +} + +SCENARIO("client_name is capped and refuses control and bidirectional characters", "[oauth][metadata][security]") +{ + GIVEN("client names of 128 and 129 bytes, empty, with a newline, NUL, C1 control, RLO, LRI or invalid UTF-8") + { + 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("only the 128-byte plain and non-Latin names are registered") + { + REQUIRE(std::holds_alternative(with_name(std::string(128U, 'a')))); + REQUIRE(std::holds_alternative(with_name("Élément \xe2\x9c\x93 アプリ"))); + for (auto const& bad : std::array{ + std::string(129U, 'a'), + std::string{}, + std::string{"a\nb"}, + std::string{"a\0b", 3U}, + std::string{"a\xc2\x85"}, + std::string{"evil\xe2\x80\xaemoc.elpmaxe"}, + std::string{"a\xe2\x81\xa6"}, + std::string{"a\xff"}, + std::string{"a\xe2\x80\xa8"}, + }) + { + REQUIRE(refusal_code(with_name(bad)) == merovingian::oauth::error_invalid_client_metadata); + } + } + } + } +} + +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") + { + auto const body = [](std::string_view key, std::string_view uri) { + return std::string{R"({"client_uri":"https://example.com/","redirect_uris":["https://example.com/cb"],")"} + + std::string{key} + R"(":")" + std::string{uri} + R"("})"; + }; + + WHEN("each is validated") + { + THEN("only the subdomain is accepted") + { + REQUIRE(refusal_code(validate(body("policy_uri", "https://docs.example.com/p"))).empty()); + REQUIRE(refusal_code(validate(body("policy_uri", "http://example.com/p"))) == + merovingian::oauth::error_invalid_client_metadata); + REQUIRE(refusal_code(validate(body("tos_uri", "https://evil.example/t"))) == + merovingian::oauth::error_invalid_client_metadata); + REQUIRE(refusal_code(validate(body("tos_uri", "https://u@example.com/t"))) == + merovingian::oauth::error_invalid_client_metadata); + REQUIRE(refusal_code(validate(body("tos_uri", "javascript:alert(1)"))) == + merovingian::oauth::error_invalid_client_metadata); + } + } + } +} + +SCENARIO("An object with more than 128 members or a repeated key is refused", "[oauth][metadata][boundary]") +{ + GIVEN("a registration padded to 129 members, and an object built with client_uri twice") + { + auto padded = std::string{R"({"client_uri":"https://example.com/","redirect_uris":["https://example.com/cb"])"}; + for (auto index = std::size_t{0U}; index < 127U; ++index) + { + padded.append(",\"x" + std::to_string(index) + "\":0"); + } + padded.append("}"); + auto repeated = Object{}; + repeated.push_back( + merovingian::canonicaljson::make_member("client_uri", Value{std::string{"https://example.com/"}})); + repeated.push_back( + merovingian::canonicaljson::make_member("client_uri", Value{std::string{"https://evil.example/"}})); + + WHEN("each is validated") + { + auto const padded_result = validate(padded); + auto const repeated_result = ClientMetadata::validate(Value{std::move(repeated)}); + + THEN("each is invalid_client_metadata and the messages quote nothing") + { + REQUIRE(refusal_code(padded_result) == merovingian::oauth::error_invalid_client_metadata); + REQUIRE(refusal_code(repeated_result) == merovingian::oauth::error_invalid_client_metadata); + REQUIRE(std::get(repeated_result).error.message().find("evil") == std::string::npos); + } + } + } +} 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..9615a8fbc --- /dev/null +++ b/tests/unit/test_oauth_cross_signing_reset_approvals.cpp @@ -0,0 +1,217 @@ +// 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 +#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)); + } + } + } +} + +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()); + } + } + } +} diff --git a/tests/unit/test_oauth_device_authorisation_store.cpp b/tests/unit/test_oauth_device_authorisation_store.cpp new file mode 100644 index 000000000..350a09396 --- /dev/null +++ b/tests/unit/test_oauth_device_authorisation_store.cpp @@ -0,0 +1,590 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +// Plan P11 (ADR-0804 to ADR-0806): the in-memory device authorisations behind POST /_merovingian/oauth2/device, the +// link page and the device code grant, and the per-address throttle on wrong user codes. Every operation takes the +// time, so no scenario sleeps. + +#include "merovingian/homeserver/DeviceAuthorisation.hpp" +#include "merovingian/homeserver/DeviceAuthorisationState.hpp" +#include "merovingian/homeserver/DeviceAuthorisationStore.hpp" +#include "merovingian/homeserver/UserCodeAttemptThrottle.hpp" +#include "merovingian/oauth/UserCode.hpp" + +#include + +#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", "stamp", 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(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)); + } + } + } + + 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", "stamp", 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", "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", "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"); + } + } + + 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", "stamp", true, start_ms + 1'000U)); + REQUIRE( + store.decide(again.key, again.attachment, "@alice:example.org", "stamp", 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_form_post_origin.cpp b/tests/unit/test_oauth_form_post_origin.cpp new file mode 100644 index 000000000..5a28b3152 --- /dev/null +++ b/tests/unit/test_oauth_form_post_origin.cpp @@ -0,0 +1,118 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +// The form-post origin rule of the OAuth 2.0 pages (ADR-0784): Origin present and equal to the base URL's origin, +// Sec-Fetch-Site, when present, same-origin; everything else refused. + +#include "merovingian/oauth/FormPostOrigin.hpp" +#include "merovingian/oauth/OAuthBaseUrl.hpp" + +#include + +#include +#include +#include +#include +#include + +namespace +{ + +using merovingian::oauth::form_post_origin; +using merovingian::oauth::form_post_origin_is_accepted; +using merovingian::oauth::OAuthBaseUrl; + +[[nodiscard]] auto base(std::string_view text) -> OAuthBaseUrl +{ + auto result = OAuthBaseUrl::read(text); + REQUIRE(std::holds_alternative(result)); + return std::get(std::move(result)); +} + +} // namespace + +SCENARIO("A form post is accepted only from this server's own origin", "[oauth][form-origin][security]") +{ + GIVEN("a base URL on the default https port, with a path") + { + auto const base_url = base("https://Matrix.Example.org/prefix/"); + + WHEN("its origin is computed") + { + THEN("it is lower-case https with no port and no path") + { + REQUIRE(form_post_origin(base_url) == "https://matrix.example.org"); + } + } + + WHEN("a post names that origin, with Sec-Fetch-Site same-origin or with none") + { + THEN("both are accepted") + { + REQUIRE(form_post_origin_is_accepted(base_url, "https://matrix.example.org", "same-origin")); + REQUIRE(form_post_origin_is_accepted(base_url, "https://matrix.example.org", std::nullopt)); + } + } + + WHEN("a post names any other Origin, or none") + { + constexpr auto refused = std::array{ + std::string_view{"null"}, + std::string_view{""}, + std::string_view{"https://matrix.example.org:443"}, + std::string_view{"https://matrix.example.org/"}, + std::string_view{"https://Matrix.Example.org"}, + std::string_view{"http://matrix.example.org"}, + std::string_view{"https://evil.example.org"}, + std::string_view{"https://matrix.example.org.evil.example"}, + std::string_view{"https://matrix.example.org:8443"}, + std::string_view{" https://matrix.example.org"}, + }; + + THEN("each is refused, and an absent Origin is refused") + { + for (auto const origin : refused) + { + REQUIRE_FALSE(form_post_origin_is_accepted(base_url, origin, "same-origin")); + } + REQUIRE_FALSE(form_post_origin_is_accepted(base_url, std::nullopt, "same-origin")); + REQUIRE_FALSE(form_post_origin_is_accepted(base_url, std::nullopt, std::nullopt)); + } + } + + WHEN("the right Origin comes with a Sec-Fetch-Site other than same-origin") + { + constexpr auto refused = + std::array{std::string_view{"cross-site"}, std::string_view{"same-site"}, std::string_view{"none"}, + std::string_view{"Same-Origin"}, std::string_view{""}}; + + THEN("each is refused") + { + for (auto const site : refused) + { + REQUIRE_FALSE(form_post_origin_is_accepted(base_url, "https://matrix.example.org", site)); + } + } + } + } + + GIVEN("a base URL that names a port") + { + auto const on_port = base("https://matrix.example.org:8448"); + auto const on_default = base("https://matrix.example.org:443"); + + WHEN("their origins are compared") + { + THEN("another port is kept and the default port is left out, as a browser writes them") + { + REQUIRE(form_post_origin(on_port) == "https://matrix.example.org:8448"); + REQUIRE(form_post_origin_is_accepted(on_port, "https://matrix.example.org:8448", "same-origin")); + REQUIRE_FALSE(form_post_origin_is_accepted(on_port, "https://matrix.example.org", "same-origin")); + REQUIRE(form_post_origin(on_default) == "https://matrix.example.org"); + REQUIRE(form_post_origin_is_accepted(on_default, "https://matrix.example.org", "same-origin")); + REQUIRE_FALSE( + form_post_origin_is_accepted(on_default, "https://matrix.example.org:443", "same-origin")); + } + } + } +} 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_hand_off_redirect.cpp b/tests/unit/test_oauth_hand_off_redirect.cpp new file mode 100644 index 000000000..5c4b24c9a --- /dev/null +++ b/tests/unit/test_oauth_hand_off_redirect.cpp @@ -0,0 +1,202 @@ +// 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", + // 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") + { + 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, " + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace +{ + +using merovingian::oauth::HtmlText; +using merovingian::oauth::Page; +using merovingian::oauth::PageDetail; +using merovingian::oauth::PageForm; +using merovingian::oauth::ParsedUri; +using merovingian::oauth::SubmitButton; +using merovingian::oauth::TextInput; + +// Unescaped text has no way in: neither a string nor a view makes an HtmlText. +static_assert(!std::is_constructible_v); +static_assert(!std::is_constructible_v); +static_assert(!std::is_default_constructible_v); + +// The markup-breaking payload, escaped. +constexpr auto hostile = std::string_view{"\">&"}; +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"); + // ADR-0784: same-origin, in the header and in the page's own meta element, which must agree: a + // same-origin form post then carries a Referer naming this server, and no other origin sees one. + REQUIRE(header(headers, "Referrer-Policy") == "same-origin"); + REQUIRE(html.find("") != std::string::npos); + REQUIRE(html.find("no-referrer") == std::string::npos); + 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"); + 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, ipv6_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:")); + // 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); + } + } + } +} + +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'")); + } + } + } + } +} diff --git a/tests/unit/test_oauth_page_response.cpp b/tests/unit/test_oauth_page_response.cpp new file mode 100644 index 000000000..3b23e15b5 --- /dev/null +++ b/tests/unit/test_oauth_page_response.cpp @@ -0,0 +1,106 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +// An OAuth 2.0 page response is marked in its type (LocalHttpResponse::page, ADR-0785): the client-server boundary +// adds no CORS header to it, while every other response keeps the CORS headers the spec requires. + +#include "merovingian/config/CorsConfig.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/LocalHttpRequest.hpp" +#include "merovingian/homeserver/LocalHttpResponse.hpp" +#include "merovingian/oauth/HtmlText.hpp" +#include "merovingian/oauth/Page.hpp" +#include "merovingian/oauth/PageHeaders.hpp" + +#include + +#include +#include +#include + +namespace +{ + +namespace hs = merovingian::homeserver; + +[[nodiscard]] auto count_header(hs::LocalHttpResponse const& response, std::string_view name) -> std::size_t +{ + auto count = std::size_t{0U}; + for (auto const& [header_name, value] : response.headers) + { + if (header_name == name) + { + ++count; + } + } + return count; +} + +[[nodiscard]] auto header_value(hs::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 + +SCENARIO("An OAuth 2.0 page response gets no CORS header at the client-server boundary", + "[oauth][page][page-response][security]") +{ + GIVEN("a hand-built page response, a JSON response, and a CORS policy that allows every origin") + { + auto page = hs::LocalHttpResponse{}; + page.status = 200U; + page.body = merovingian::oauth::Page{merovingian::oauth::HtmlText{"Sign in"}}.render(); + page.headers = merovingian::oauth::page_headers(); + page.page = true; + auto const page_headers_before = page.headers; + auto const body_before = page.body; + auto json = hs::LocalHttpResponse{}; + json.status = 200U; + json.body = "{}"; + auto cors = merovingian::config::CorsConfig{}; + cors.allowed_origins = {"*"}; + auto request = hs::LocalHttpRequest{"GET", "/_merovingian/oauth2/authorize", {}, {}}; + request.headers.push_back({"Origin", "https://evil.example"}); + auto preflight = hs::LocalHttpRequest{"OPTIONS", "/_merovingian/oauth2/authorize", {}, {}}; + preflight.headers.push_back({"Origin", "https://evil.example"}); + + WHEN("the boundary headers are applied to each, for a request and a preflight") + { + auto page_preflight = page; + hs::apply_client_response_headers(request, page, cors); + hs::apply_client_response_headers(preflight, page_preflight, cors); + hs::apply_client_response_headers(request, json, cors); + + THEN("the page has no Access-Control or Vary header, only nosniff added, and its body unchanged") + { + for (auto const* response : {&page, &page_preflight}) + { + for (auto const& [name, value] : response->headers) + { + REQUIRE_FALSE(name.starts_with("Access-Control-")); + REQUIRE(name != "Vary"); + } + REQUIRE(count_header(*response, "X-Content-Type-Options") == 1U); + REQUIRE(response->headers.size() == page_headers_before.size() + 1U); + REQUIRE(response->body == body_before); + REQUIRE(header_value(*response, "Content-Type") == "text/html; charset=utf-8"); + REQUIRE(header_value(*response, "Referrer-Policy") == "same-origin"); + } + } + + THEN("a response that is not a page still gets the CORS headers") + { + REQUIRE(header_value(json, "Access-Control-Allow-Origin") == "*"); + REQUIRE(count_header(json, "X-Content-Type-Options") == 1U); + } + } + } +} diff --git a/tests/unit/test_oauth_pending_authorisation_store.cpp b/tests/unit/test_oauth_pending_authorisation_store.cpp new file mode 100644 index 000000000..20c35b259 --- /dev/null +++ b/tests/unit/test_oauth_pending_authorisation_store.cpp @@ -0,0 +1,393 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +// Plan P5 (ADR-0782): the in-memory pending authorisations behind GET /_merovingian/oauth2/authorize. Hashed, bound to +// the browser, ten minutes, bounded, never evicting a live entry. + +#include "merovingian/homeserver/OAuthSecret.hpp" +#include "merovingian/homeserver/PendingAuthorisation.hpp" +#include "merovingian/homeserver/PendingAuthorisationStore.hpp" +#include "merovingian/oauth/ResponseMode.hpp" + +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace +{ + +using merovingian::homeserver::PendingAuthorisation; +using merovingian::homeserver::PendingAuthorisationStore; + +constexpr auto start_ms = std::uint64_t{1'000'000U}; +constexpr auto browser = std::string_view{"browser-binding-token"}; + +[[nodiscard]] auto request_for(std::string client_id) -> PendingAuthorisation +{ + auto authorisation = PendingAuthorisation{}; + authorisation.client_id = std::move(client_id); + authorisation.redirect_uri = "https://app.example.org/callback"; + authorisation.response_mode = merovingian::oauth::ResponseMode::fragment; + authorisation.state = "client-state"; + authorisation.code_challenge = "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"; + authorisation.device_id = "DEVICEID"; + authorisation.scope = "urn:matrix:client:api:* urn:matrix:client:device:DEVICEID"; + authorisation.create_account = true; + authorisation.login_hint = "@alice:example.org"; + // The store sets these three itself. + authorisation.user_id = "@mallory:example.org"; + authorisation.client_address_key = "ignored"; + authorisation.created_at_ms = 7U; + return authorisation; +} + +[[nodiscard]] auto create(PendingAuthorisationStore& store, std::string client_id, std::string_view address, + std::uint64_t now_ms) -> std::variant +{ + return store.create(request_for(std::move(client_id)), browser, address, now_ms); +} + +[[nodiscard]] auto identifier_of(std::variant const& created) + -> std::string +{ + REQUIRE(std::holds_alternative(created)); + return std::get(created); +} + +} // namespace + +SCENARIO("A pending authorisation is stored under a fresh identifier and read back only with its browser token", + "[oauth][oauth-pending]") +{ + // The store draws identifiers from libsodium's random generator and hashes them, so the library is + // initialised before any GIVEN runs. + REQUIRE(sodium_init() >= 0); + GIVEN("a store holding one request") + { + // `request_for` fills user_id, client_address_key and created_at_ms with wrong values on purpose: the store + // must overwrite them, so a caller can never pre-sign-in a request or misstate its address or age. + auto store = PendingAuthorisationStore{}; + auto const identifier = identifier_of(create(store, "client-a", "198.51.100.7", start_ms)); + + WHEN("it is found with its identifier and its browser token") + { + auto const found = store.find(identifier, browser, start_ms + 1U); + + THEN("the request comes back as stored, with the fields the store owns set by the store") + { + // Every field the client chose must survive unchanged: the code, the redirect and the token request + // are later checked against these values. + REQUIRE(found.has_value()); + CHECK(found->client_id == "client-a"); + CHECK(found->redirect_uri == "https://app.example.org/callback"); + CHECK(found->response_mode == merovingian::oauth::ResponseMode::fragment); + CHECK(found->state == "client-state"); + CHECK(found->code_challenge == "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"); + CHECK(found->device_id == "DEVICEID"); + CHECK(found->scope == "urn:matrix:client:api:* urn:matrix:client:device:DEVICEID"); + CHECK(found->create_account); + CHECK(found->login_hint == std::optional{"@alice:example.org"}); + // No one has signed in yet, whatever the request said; the address and the time are the store's. + CHECK(found->user_id.empty()); + CHECK(found->client_address_key == "198.51.100.7"); + CHECK(found->created_at_ms == start_ms); + } + + THEN("the identifier is 64 hex digits and is not what the store keeps") + { + REQUIRE(identifier.size() == 64U); + CHECK(identifier.find_first_not_of("0123456789abcdef") == std::string::npos); + // 32 random bytes in hex. The store keys entries by the hash, so a copy of its memory does not give + // the identifiers a browser could post (ADR-0782). + CHECK(merovingian::homeserver::oauth_secret_hash(identifier) != std::optional{identifier}); + } + } + + WHEN("it is looked up with a wrong browser token, and with an unknown identifier") + { + auto const wrong_token = store.find(identifier, "another-browser", start_ms + 1U); + auto const unknown = store.find(std::string(64U, 'a'), browser, start_ms + 1U); + // An empty token is tried too: only the one token the entry was bound to may match, never an empty value. + auto const empty_token = store.find(identifier, "", start_ms + 1U); + + THEN("both answer alike, nothing, and the entry is still held") + { + CHECK_FALSE(wrong_token.has_value()); + CHECK_FALSE(unknown.has_value()); + CHECK_FALSE(empty_token.has_value()); + // A failed lookup must not remove the entry: otherwise anyone holding a leaked identifier could end + // another browser's sign-in by sending it with any wrong cookie. + CHECK(store.size() == 1U); + CHECK(store.find(identifier, browser, start_ms + 2U).has_value()); + } + } + + WHEN("a wrong browser token tries to record a user and to consume it") + { + // The two writes an attacker would want: attach their own account to the victim's request, or spend it. + 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") + { + CHECK_FALSE(recorded); + CHECK_FALSE(consumed.has_value()); + auto const found = store.find(identifier, browser, start_ms); + REQUIRE(found.has_value()); + CHECK(found->user_id.empty()); + } + } + + WHEN("the authenticated user is recorded and the entry is consumed") + { + REQUIRE(store.record_user(identifier, browser, "@alice:example.org", "stamp", start_ms + 10U)); + auto const consumed = store.consume(identifier, browser, start_ms + 20U); + // Consumed twice: an approval is one use, so a replayed approve form finds nothing. + auto const again = store.consume(identifier, browser, start_ms + 30U); + + THEN("the consumed entry names the user, and it is gone") + { + 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); + // The per-client index forgets it too: a stale entry there would make the client look busy to the + // registration cap and the retention sweep, which ask that index. + CHECK(store.live_count_for_client("client-a", start_ms + 30U) == 0U); + } + } + } + + GIVEN("an empty store") + { + auto store = PendingAuthorisationStore{}; + + WHEN("a request is offered with no browser token") + { + // An entry bound to nothing could be continued by any browser that learns its identifier. + auto const created = store.create(request_for("client-a"), "", "198.51.100.7", start_ms); + + THEN("it is refused and nothing is stored") + { + REQUIRE(std::holds_alternative(created)); + CHECK(std::get(created) == + PendingAuthorisationStore::Refusal::no_browser_token); + CHECK(store.size() == 0U); + } + } + + WHEN("two requests are stored") + { + auto const first = identifier_of(create(store, "client-a", "198.51.100.7", start_ms)); + auto const second = identifier_of(create(store, "client-a", "198.51.100.7", start_ms)); + + THEN("each has its own identifier") + { + CHECK(first != second); + CHECK(store.size() == 2U); + } + } + } +} + +SCENARIO("A pending authorisation lives ten minutes from its creation, to the millisecond", "[oauth][oauth-pending]") +{ + REQUIRE(sodium_init() >= 0); + GIVEN("a store holding one request created at a known time") + { + auto store = PendingAuthorisationStore{}; + auto const identifier = identifier_of(create(store, "client-a", "198.51.100.7", start_ms)); + auto const end_ms = start_ms + PendingAuthorisationStore::lifetime_ms; + + WHEN("it is read one millisecond before its end") + { + 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") + { + REQUIRE(found.has_value()); + CHECK(store.holds_live_entry_for_client("client-a", end_ms - 1U)); + CHECK_FALSE(store.holds_live_entry_for_client("client-a", end_ms)); + } + } + + WHEN("it is read at exactly its end") + { + auto const found = store.find(identifier, browser, end_ms); + + THEN("it behaves as absent and has been removed") + { + CHECK_FALSE(found.has_value()); + CHECK(store.size() == 0U); + CHECK(store.live_count_for_client("client-a", end_ms) == 0U); + } + } + + WHEN("it is consumed at exactly its end") + { + auto const consumed = store.consume(identifier, browser, end_ms); + + THEN("nothing is returned") + { + CHECK_FALSE(consumed.has_value()); + } + } + } +} + +SCENARIO("The pending authorisations are capped per address and in all, and a live entry is never evicted", + "[oauth][oauth-pending][cap]") +{ + REQUIRE(sodium_init() >= 0); + GIVEN("one address holding its cap of live entries") + { + auto store = PendingAuthorisationStore{}; + auto identifiers = std::vector{}; + for (auto index = std::size_t{0U}; index < PendingAuthorisationStore::max_entries_per_address; ++index) + { + identifiers.push_back(identifier_of(create(store, "client-a", "198.51.100.7", start_ms + index))); + } + + WHEN("the same address asks again, and another address asks") + { + auto const refused = create(store, "client-a", "198.51.100.7", start_ms + 100U); + auto const other = create(store, "client-a", "203.0.113.9", start_ms + 100U); + + THEN("the first is refused for its address, the second is stored, and every earlier entry is live") + { + REQUIRE(std::holds_alternative(refused)); + CHECK(std::get(refused) == + PendingAuthorisationStore::Refusal::address_full); + CHECK(std::holds_alternative(other)); + for (auto const& identifier : identifiers) + { + CHECK(store.find(identifier, browser, start_ms + 100U).has_value()); + } + } + } + + WHEN("the oldest entry has expired and the address asks again") + { + auto const later = start_ms + PendingAuthorisationStore::lifetime_ms; + auto const created = create(store, "client-a", "198.51.100.7", later); + + THEN("the expired entry was purged to make room, and the others are still live") + { + CHECK(std::holds_alternative(created)); + CHECK_FALSE(store.find(identifiers.front(), browser, later).has_value()); + CHECK(store.find(identifiers.back(), browser, later).has_value()); + } + } + + WHEN("one entry is consumed and the address asks again") + { + REQUIRE(store.consume(identifiers.front(), browser, start_ms + 50U).has_value()); + auto const created = create(store, "client-a", "198.51.100.7", start_ms + 50U); + + THEN("the freed place is used") + { + CHECK(std::holds_alternative(created)); + } + } + } + + GIVEN("a store holding its total cap of live entries from many addresses") + { + auto store = PendingAuthorisationStore{}; + auto first = std::string{}; + for (auto index = std::size_t{0U}; index < PendingAuthorisationStore::max_entries; ++index) + { + auto const address = + "address-" + std::to_string(index / PendingAuthorisationStore::max_entries_per_address); + auto identifier = identifier_of(create(store, "client-" + std::to_string(index % 3U), address, start_ms)); + if (index == 0U) + { + first = std::move(identifier); + } + } + + WHEN("a new address asks while every entry is live") + { + auto const refused = create(store, "client-new", "203.0.113.200", start_ms + 1U); + + THEN("it is refused, nothing was evicted, and the first entry is still live") + { + REQUIRE(std::holds_alternative(refused)); + CHECK(std::get(refused) == + PendingAuthorisationStore::Refusal::store_full); + CHECK(store.size() == PendingAuthorisationStore::max_entries); + CHECK(store.find(first, browser, start_ms + 1U).has_value()); + } + } + + WHEN("the entries have expired and a new address asks") + { + auto const later = start_ms + PendingAuthorisationStore::lifetime_ms; + auto const created = create(store, "client-new", "203.0.113.200", later); + + THEN("the expired entries were purged and it is stored") + { + CHECK(std::holds_alternative(created)); + CHECK(store.size() == 1U); + } + } + } +} + +SCENARIO("The live pending authorisations of a client are counted without a scan", "[oauth][oauth-pending]") +{ + REQUIRE(sodium_init() >= 0); + GIVEN("two entries for one client, made a minute apart, and one for another") + { + auto store = PendingAuthorisationStore{}; + auto const early = identifier_of(create(store, "client-a", "198.51.100.7", start_ms)); + std::ignore = identifier_of(create(store, "client-a", "198.51.100.8", start_ms + 60'000U)); + std::ignore = identifier_of(create(store, "client-b", "198.51.100.9", start_ms)); + + WHEN("the counts are read while all are live, after the earlier one expired, and after all expired") + { + auto const all_live = store.live_count_for_client("client-a", start_ms + 1U); + auto const other = store.live_count_for_client("client-b", start_ms + 1U); + auto const none = store.live_count_for_client("client-c", start_ms + 1U); + auto const held_after_early = + store.holds_live_entry_for_client("client-a", start_ms + PendingAuthorisationStore::lifetime_ms); + auto const after_early = + store.live_count_for_client("client-a", start_ms + PendingAuthorisationStore::lifetime_ms); + auto const held_after_all = store.holds_live_entry_for_client( + "client-a", start_ms + 60'000U + PendingAuthorisationStore::lifetime_ms); + + THEN("each answer counts only the client's live entries") + { + CHECK(all_live == 2U); + CHECK(other == 1U); + CHECK(none == 0U); + CHECK(held_after_early); + CHECK(after_early == 1U); + CHECK_FALSE(held_after_all); + } + } + + WHEN("the earlier entry is consumed") + { + REQUIRE(store.consume(early, browser, start_ms + 1U).has_value()); + + THEN("the client's count drops by one") + { + CHECK(store.live_count_for_client("client-a", start_ms + 1U) == 1U); + CHECK(store.holds_live_entry_for_client("client-a", start_ms + 1U)); + } + } + } +} diff --git a/tests/unit/test_oauth_pkce.cpp b/tests/unit/test_oauth_pkce.cpp new file mode 100644 index 000000000..d720b6a27 --- /dev/null +++ b/tests/unit/test_oauth_pkce.cpp @@ -0,0 +1,189 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// oauth PKCE (RFC 7636, S256 only, ADR-0768) and the crypto::sha256 primitive it hashes with. + +#include "merovingian/crypto/Encoding.hpp" +#include "merovingian/crypto/Sha256.hpp" +#include "merovingian/oauth/Pkce.hpp" + +#include + +#include +#include +#include + +namespace +{ + +using merovingian::oauth::pkce_challenge_is_valid; +using merovingian::oauth::pkce_s256_matches; +using merovingian::oauth::pkce_verifier_is_valid; + +// RFC 7636 appendix B. +constexpr auto rfc_verifier = std::string_view{"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"}; +constexpr auto rfc_challenge = std::string_view{"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"}; + +} // namespace + +SCENARIO("crypto::sha256 matches the FIPS 180-2 test vectors", "[crypto][sha256]") +{ + GIVEN("the inputs \"abc\" and the empty string") + { + WHEN("they are hashed") + { + auto const abc = merovingian::crypto::sha256("abc"); + auto const empty = merovingian::crypto::sha256(""); + + THEN("each digest is 32 bytes with the published value") + { + REQUIRE(abc.has_value()); + REQUIRE(empty.has_value()); + REQUIRE(abc->size() == merovingian::crypto::sha256_digest_bytes); + auto const abc_hex = + merovingian::crypto::to_hex({reinterpret_cast(abc->data()), abc->size()}); + auto const empty_hex = + merovingian::crypto::to_hex({reinterpret_cast(empty->data()), empty->size()}); + REQUIRE(abc_hex == "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"); + REQUIRE(empty_hex == "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"); + } + } + } +} + +SCENARIO("The RFC 7636 appendix B verifier matches its challenge", "[oauth][pkce]") +{ + GIVEN("the appendix B code_verifier and code_challenge") + { + WHEN("the verifier is checked against the challenge") + { + auto const matches = pkce_s256_matches(rfc_verifier, rfc_challenge); + + THEN("it matches, and both are valid on their own") + { + REQUIRE(matches); + REQUIRE(pkce_verifier_is_valid(rfc_verifier)); + REQUIRE(pkce_challenge_is_valid(rfc_challenge)); + } + } + } +} + +SCENARIO("A verifier that differs in one character does not match", "[oauth][pkce][security]") +{ + GIVEN("the appendix B verifier with its last character changed") + { + auto verifier = std::string{rfc_verifier}; + verifier.back() = 'j'; + + WHEN("it is checked against the appendix B challenge") + { + auto const matches = pkce_s256_matches(verifier, rfc_challenge); + + THEN("it does not match") + { + REQUIRE_FALSE(matches); + } + } + } +} + +SCENARIO("The verifier length bounds are 43 and 128", "[oauth][pkce][boundary]") +{ + GIVEN("verifiers of 42, 43, 128 and 129 unreserved characters") + { + auto const v42 = std::string(42U, 'a'); + auto const v43 = std::string(43U, 'a'); + auto const v128 = std::string(128U, '~'); + auto const v129 = std::string(129U, '~'); + + WHEN("each is validated") + { + THEN("only 43 and 128 pass") + { + REQUIRE_FALSE(pkce_verifier_is_valid(v42)); + REQUIRE(pkce_verifier_is_valid(v43)); + REQUIRE(pkce_verifier_is_valid(v128)); + REQUIRE_FALSE(pkce_verifier_is_valid(v129)); + REQUIRE_FALSE(pkce_verifier_is_valid("")); + } + } + } +} + +SCENARIO("A verifier holding a character outside the unreserved set is refused", "[oauth][pkce][security]") +{ + GIVEN("43-character verifiers each carrying one forbidden byte") + { + auto const forbidden = std::string_view{"+/= %!*\x7f"}; + + WHEN("each is validated") + { + THEN("every one is refused, and a NUL is refused too") + { + for (auto const value : forbidden) + { + auto verifier = std::string(43U, 'a'); + verifier[20] = value; + REQUIRE_FALSE(pkce_verifier_is_valid(verifier)); + } + auto with_nul = std::string(43U, 'a'); + with_nul[0] = '\0'; + REQUIRE_FALSE(pkce_verifier_is_valid(with_nul)); + auto non_ascii = std::string(42U, 'a'); + non_ascii.append("\xc3\xa9"); + REQUIRE_FALSE(pkce_verifier_is_valid(non_ascii)); + } + } + } +} + +SCENARIO("A challenge must be exactly 43 canonical base64url characters", "[oauth][pkce][security]") +{ + GIVEN("challenges that are padded, too short, too long, standard base64, or non-canonical") + { + auto const padded = std::string{rfc_challenge} + "="; + auto const short_one = std::string{rfc_challenge.substr(0U, 42U)}; + auto const long_one = std::string{rfc_challenge} + "A"; + auto standard = std::string{rfc_challenge}; + standard[5] = '+'; + // `cM` ends the RFC challenge; `cN` decodes to the same 32 bytes with a set unused bit. + auto non_canonical = std::string{rfc_challenge}; + non_canonical.back() = 'N'; + + WHEN("each is validated") + { + THEN("every one is refused and none can match the verifier") + { + for (auto const& challenge : {padded, short_one, long_one, standard, non_canonical}) + { + REQUIRE_FALSE(pkce_challenge_is_valid(challenge)); + REQUIRE_FALSE(pkce_s256_matches(rfc_verifier, challenge)); + } + } + } + } +} + +SCENARIO("An invalid verifier never matches, even against its own hash", "[oauth][pkce][security]") +{ + GIVEN("a 42-character verifier and the challenge computed from it") + { + auto const verifier = std::string(42U, 'a'); + auto const digest = merovingian::crypto::sha256(verifier); + REQUIRE(digest.has_value()); + auto const challenge = merovingian::crypto::base64_urlsafe_encode(*digest); + REQUIRE(challenge.has_value()); + + WHEN("they are checked") + { + auto const matches = pkce_s256_matches(verifier, *challenge); + + THEN("the short verifier is refused") + { + REQUIRE(pkce_challenge_is_valid(*challenge)); + REQUIRE_FALSE(matches); + } + } + } +} diff --git a/tests/unit/test_oauth_redirect_uri.cpp b/tests/unit/test_oauth_redirect_uri.cpp new file mode 100644 index 000000000..34b0a7b9b --- /dev/null +++ b/tests/unit/test_oauth_redirect_uri.cpp @@ -0,0 +1,502 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// oauth::ParsedUri, oauth::ClientUri and the redirect URI rules (spec v1.19 Client-Server API "Redirect URI +// validation", RFC 8252 section 7; ADR-0770, ADR-0771). + +#include "merovingian/core/ErrorCode.hpp" +#include "merovingian/oauth/ApplicationType.hpp" +#include "merovingian/oauth/ClientUri.hpp" +#include "merovingian/oauth/OAuthErrorCodes.hpp" +#include "merovingian/oauth/ParsedUri.hpp" +#include "merovingian/oauth/RedirectUriRules.hpp" + +#include + +#include +#include +#include +#include +#include +#include +#include + +namespace +{ + +using merovingian::oauth::ApplicationType; +using merovingian::oauth::ClientUri; +using merovingian::oauth::OAuthRefusal; +using merovingian::oauth::ParsedUri; + +[[nodiscard]] auto client(std::string_view text) -> ClientUri +{ + auto read = ClientUri::read(text); + REQUIRE(std::holds_alternative(read)); + return std::get(std::move(read)); +} + +[[nodiscard]] auto accepted(std::string_view uri, ApplicationType type, ClientUri const& base) -> bool +{ + return std::holds_alternative(merovingian::oauth::validate_redirect_uri(uri, type, base)); +} + +[[nodiscard]] auto refused_as_redirect(std::string_view uri, ApplicationType type, ClientUri const& base) -> bool +{ + auto const result = merovingian::oauth::validate_redirect_uri(uri, type, base); + auto const* refusal = std::get_if(&result); + return refusal != nullptr && refusal->error_code == merovingian::oauth::error_invalid_redirect_uri; +} + +[[nodiscard]] auto reads(std::string_view text) -> bool +{ + return std::holds_alternative(ParsedUri::read(text)); +} + +[[nodiscard]] auto matches(std::string_view requested, ApplicationType type, std::vector const& registered) + -> bool +{ + return merovingian::oauth::match_redirect_uri(requested, type, registered).has_value(); +} + +} // namespace + +SCENARIO("The URI reader splits an absolute URI into its parts", "[oauth][uri]") +{ + GIVEN("an https URI with a port, path and query, and a private-use URI with no authority") + { + WHEN("each is read") + { + auto web = ParsedUri::read("https://App.Example.com:5173/cb/x?query=value&b=%2F"); + auto native = ParsedUri::read("com.example.app:/callback"); + + THEN("every field is the bytes given, and the CSP source is built from scheme, host and port") + { + REQUIRE(std::holds_alternative(web)); + auto const& w = std::get(web); + REQUIRE(w.scheme() == "https"); + REQUIRE(w.has_authority()); + REQUIRE(w.host() == "App.Example.com"); + REQUIRE(w.port() == std::uint16_t{5173U}); + REQUIRE(w.path() == "/cb/x"); + REQUIRE(w.has_query()); + REQUIRE(w.query() == "query=value&b=%2F"); + REQUIRE(w.csp_source() == "https://App.Example.com:5173"); + + REQUIRE(std::holds_alternative(native)); + auto const& n = std::get(native); + REQUIRE_FALSE(n.has_authority()); + REQUIRE(n.host().empty()); + REQUIRE(n.path() == "/callback"); + REQUIRE(n.csp_source() == "com.example.app:"); + } + } + } +} + +SCENARIO("The URI reader refuses hostile and ambiguous forms", "[oauth][uri][security]") +{ + GIVEN("URIs with a fragment, userinfo, escapes in the host, control bytes, backslashes and bad ports") + { + auto const refused = std::array{ + "https://example.com/cb#fragment", + "https://example.com/cb#", + "https://user@example.com/", + "https://user:pass@example.com/", + "https://@example.com/", + "https://exa%6Dple.com/", + "https://example.com./", + "https://.example.com/", + "https://exa..mple.com/", + "https://-example.com/", + "https://example-.com/", + "https://exa_mple.com/", + "https://example.com\\@evil.example/", + "https://example.com/\\evil", + "https://example.com/a b", + "https://example.com/\t", + "https://example.com:0/", + "https://example.com:65536/", + "https://example.com:0443/", + "https://example.com:/", + "https://example.com:12a/", + "https:///path", + "https://[::1/", + "https://[example.com]/", + "https://example.com/%zz", + "https://example.com/%4", + "https://example.com/