diff --git a/proposals/4145-simple-verified-accounts.md b/proposals/4145-simple-verified-accounts.md new file mode 100644 index 00000000000..1ad8d163193 --- /dev/null +++ b/proposals/4145-simple-verified-accounts.md @@ -0,0 +1,105 @@ +# MSC4145: Simple verified accounts + +[Server notices](https://spec.matrix.org/v1.10/client-server-api/#server-notices) and similar alerts +sent by servers are typically sent by a general purpose user such as `@support:example.org`. These +messages can [look like a phishing attempt](https://github.com/element-hq/element-meta/issues/1759) +when they lack any "official" markings. + +This proposal introduces a simple server-local verification mechanism to identify "verified" +accounts. This proposal does *not* introduce a mechanism to request/assign verification, nor manage +that verification - this is left as an implementation detail under this proposal, and may be +improved by a future MSC. + +## Proposal + +The user's [global profile](https://spec.matrix.org/v1.10/client-server-api/#profiles) has a new +*optional* `m.verified` property added, as shown by the below endpoints. + +`m.verified` takes on a slightly weird shape to allow for future expansion, such as the potential +for a signed object, attestation, etc. The `m.verified` object can only contain a single boolean +currently: `verified`. When `m.verified` is supplied, `verified` can only be `true` (otherwise the +user is considered "unverified" or "default"). + +[`GET /_matrix/client/v3/profile/{userId}`](https://spec.matrix.org/v1.10/client-server-api/#get_matrixclientv3profileuserid) +response: +```jsonc +{ + "displayname": "Support", + "avatar_url": "mxc://example.org/abc123", + "m.verified": { // new! + "verified": true + } +} +``` + +If the user is not verified, `m.verified` will not be present. + +**New Endpoint** - `GET /_matrix/client/v3/profile/{userId}/m.verified` + +*No request body.* + +Response: +```jsonc +{ + "m.verified": { + "verified": true + } +} +``` + +The endpoint behaves similar to [`GET /_matrix/client/v3/profile/{userId}/displayname`](https://spec.matrix.org/v1.10/client-server-api/#get_matrixclientv3profileuseriddisplayname): +if the user doesn't exist or is not verified locally on the server, the endpoint returns 404 `M_NOT_FOUND`. +Note that this new endpoint does *not* go over federation to determine verified status - for this +proposal, verification is very intentionally a server-local state. + +Unlike `GET /displayname`, there is deliberately no `PUT /m.verified` partner endpoint. + +### Applicability + +Verified users SHOULD have a badge next to their name when they send a message or invite within the +client's UI, regardless of which room they're in. Clients SHOULD use a custom graphic to denote this +verified badge rather than an emoji to prevent phishing attempts from other users. + +Clients SHOULD also show a warning or "unverified" badge when a sender appears to be trying to +indicate that they're verified when they're not. For example, `Alice ☑️` or `Alice [VERIFIED]`. + +It is left as an implementation detail for how to assign/request verification status. A server might, +for example, put a policy in place where only specific individuals receive verification status with +no opportunity to apply. Another server might require requests to be sent to `@support:example.org`. + +### Caching + +A given user's name can appear in a number of places within a client, potentially leading to *thousands* +of calls for verification status. To help reduce this request spam, calls to `GET /_matrix/client/v3/profile/{userId}/m.verified` +MUST be cached by clients, either by respecting the [`Cache-Control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) +header, or for a minimum of 24 hours. Similarly, `m.verified` on the general `/profile/{userId}` +endpoint must be cached for at least 24 hours. + +Verification status is not expected to change often, so longer cache values are preferred. + +## Potential issues + +This proposal doesn't work over federation. This is a feature, not a bug. Communicating verification +over federation would ideally mean having a method for end clients to confirm the verification +without the use of the attached homeserver. Such a problem is challenging to solve quickly. + +## Alternatives + +Significant alternatives are implied throughout. Namely, a proper verification system could be +introduced instead, though such a system requires significant engineering effort. + +## Security considerations + +Clients MUST be cautious and warn users of possible phishing attempts relating to verification, as +discussed earlier in this MSC. + +## Unstable prefix + +While this MSC is not considered stable, the following transformations apply: + +* `GET /_matrix/client/v3/profile/{userId}/m.verified` becomes `GET /_matrix/client/unstable/org.matrix.msc4145/profile/{userId}/org.matrix.msc4145.verified` +* `m.verified` becomes `org.matrix.msc4145.verified` + +## Dependencies + +This MSC has no direct dependencies itself.