Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
43 commits
Select commit Hold shift + click to select a range
dd2e6ba
Plan the built-in OAuth 2.0 API and start 1.1.0 (ADR-0760 to ADR-0764)
James-Chapman Nov 15, 2026
dee45a9
Add strict form-body and Cookie readers and a __Host- cookie builder …
James-Chapman Nov 15, 2026
61d2744
Refuse a response head that cannot be written safely, and match heade…
James-Chapman Nov 15, 2026
d7ea4e9
Add the oauth module with PKCE S256 and the scope parser, and crypto:…
James-Chapman Nov 16, 2026
47a377a
Add the strict URI reader, redirect URI rules and client metadata val…
James-Chapman Nov 16, 2026
55aa245
Add the page renderer and page headers to oauth, and the module's gui…
James-Chapman Nov 16, 2026
84038b9
Link observability and platform into the OAuth fuzz targets
James-Chapman Nov 16, 2026
2e1d6e9
Serve the OAuth 2.0 server metadata behind server.oauth.*, and refuse…
James-Chapman Nov 16, 2026
a8d55c5
Run the form, cookie and OAuth fuzz targets from the fuzz runner
James-Chapman Nov 16, 2026
d27963f
Add migration 002 with the OAuth 2.0 client and session tables (ADR-0…
James-Chapman Nov 16, 2026
6059cd2
Serve OAuth 2.0 client registration at /_merovingian/oauth2/register …
James-Chapman Nov 16, 2026
e383c4c
Wrap the 1.1.0 release notes within the changelog's line limit
James-Chapman Nov 16, 2026
96d0343
Add the OAuth 2.0 phase 5a building blocks (ADR-0782 to ADR-0786)
James-Chapman Nov 16, 2026
8667d82
Serve the OAuth 2.0 authorisation pages at /_merovingian/oauth2/autho…
James-Chapman Nov 16, 2026
017692c
Serve the OAuth 2.0 token and revocation endpoints (ADR-0791 to ADR-0…
James-Chapman Nov 16, 2026
bc55dd7
Serve the OAuth 2.0 account pages and the m.oauth UIA stage (ADR-0796…
James-Chapman Nov 16, 2026
10afc04
Document the OAuth 2.0 account pages and record ADR-0796 to ADR-0798
James-Chapman Nov 16, 2026
31617f9
Accept a polling m.oauth retry and refuse page text in member initial…
James-Chapman Nov 16, 2026
cd52c38
Turn the legacy authentication API off with server.oauth.legacy_api_e…
James-Chapman Nov 16, 2026
09dcc3c
Hand legacy SSO logins off to the OAuth 2.0 pages with a confirmation…
James-Chapman Nov 16, 2026
e05e8cd
Answer an exception that escapes a client-server handler with 500 M_U…
James-Chapman Nov 16, 2026
20bcdca
Serve the OAuth 2.0 device authorization grant (ADR-0804 to ADR-0806)
James-Chapman Nov 16, 2026
96ca4e2
End an OAuth sign-in in progress when the password changes (ADR-0807)
James-Chapman Nov 16, 2026
8034421
Delete an OAuth session row with the last credential of its device (A…
James-Chapman Nov 16, 2026
4079b7a
Bind a cross-signing reset approval to the OAuth device that asked (A…
James-Chapman Nov 16, 2026
5a96eb1
Log only a registered client_id, finish the code grant before its com…
James-Chapman Nov 16, 2026
b236289
Answer an exception escaping one of the server's own pages with an er…
James-Chapman Nov 16, 2026
dc71e3b
Tighten the OAuth URI, client metadata and hand-off rules (ADR-0811)
James-Chapman Nov 16, 2026
38d15c0
Read a page query's bare name or empty field as not sent (ADR-0765)
James-Chapman Nov 16, 2026
acfbe7b
Build every device and token insert through one statement helper each
James-Chapman Nov 16, 2026
7e54dc0
Bring the 1.1.0 CHANGELOG and two ADR notes up to date
James-Chapman Nov 16, 2026
08b23e4
List a device POST /refresh heals under its stored display name
James-Chapman Nov 16, 2026
bad2e61
Add the OAuth 2.0 API to the threat model and the review checklist
James-Chapman Nov 16, 2026
21aa08d
Record the OAuth 2.0 plan's status and what is still open
James-Chapman Nov 16, 2026
912331f
Include <typeinfo> where the exception type name is read
James-Chapman Nov 16, 2026
3e87655
Derive the OAuth client ID key per registration, not for life
James-Chapman Nov 16, 2026
fadf4f3
Set the FreeBSD service's locked-memory limit in its rc.d script
James-Chapman Nov 16, 2026
3cddf44
Move ADR-0760 to ADR-0765 of this branch to ADR-0812 to ADR-0817
James-Chapman Nov 16, 2026
a8a4b42
Merge origin/main (1.0.3) into feature/oauth-20-v110
James-Chapman Nov 16, 2026
6c969a0
Remove every applied migration's tables when a test makes the schema …
James-Chapman Nov 16, 2026
592fe56
Throw std::logic_error from the page-text checks; mark the loopback h…
James-Chapman Nov 16, 2026
0c0681c
Address CodeQL's code-quality alerts on the OAuth 2.0 changes
James-Chapman Nov 16, 2026
89f7cd9
Write the client metadata rule list as sentences
James-Chapman Nov 17, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
40 changes: 40 additions & 0 deletions .agent/skills/merovingian-review/references/module-invariants.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

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

Expand Down Expand Up @@ -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`
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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`
Expand Down
6 changes: 4 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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 |
Expand Down
Loading
Loading