Skip to content

Matrix Based Notifications [Proposal]

Jump to bottom
Rok Biderman edited this page Aug 1, 2018 · 1 revision

Matrix Based Notifications

Overview

The project consists of a notification system for the Umbrella app that uses the Matrix protocol for delivering and reading notifications.

Goals

Security: using innate Matrix encryption, the messages will be encrypted. A solution for user management needs to be defined.

Transparency: both Synapse and this project will be open source.

Specifications

A Synapse instance is required to use the notification server. Synapse does not requires to be exposed to the outside network if the server is running in the same machine (recommended).

For each user the server will use the Empty Room (message with yourself) to store the notification that are user related. Other rooms will be used for group related notifications.

The process that allows an user to join a group needs to be defined. The idea, for now, is the following: The admin selects a contact in order to add it to the group (using the phone number).

It specifies an email to send the invitation. An email is sent to an user with the link for subscribing. The user clicks the link, it gets prompted for account creation or login.

The server verifies that phone number used is the same as the one specified by the admin.

If it’s a new account and everything is fine, the account is created and the user is added to the group.

If the user already exists (phone number is used) the user is prompted to log in, and it gets added to the group once logged successfully.

The call for the notification endpoint will return a series of events, each with its ID, and a PrevBatch. If it’s blank there are no older notifications, otherwise it can be used on the next call to go backwards, and look for more.

There will be a parameter called “PrevBatch” than allows for pagination. If it’s returned a blank value the beginning of the list has been reached, otherwise the returned value, passed to the pagination endpoint, will allow to go back further.

Milestones

  • Authentication handling
  • Create the endpoints for login, logout and register
  • Notification handling
  • Endpoints for sending and receiving notifications.
  • Group handling
  • Process and endpoint for managing user’s group
  • Synapse
  • User Creation
  • The normal user creation flow is made by three steps
  • Account creation
  • A POST call to /_matrix/client/r0/register than returns a session ID.
curl "https://comms.secfirst.org/_matrix/client/r0/register?" --data-binary '{"auth":{},"username":"testuser","password":"testuser","bind_email":true,"bind_msisdn":true,"x_show_msisdn":true}'
{"session": "vtnimoEKSQyYOTqhKiqpOXHi", "params": {}, "flows": [{"stages": ["m.login.dummy"]}, {"stages": ["m.login.email.identity"]}, {"stages": ["m.login.msisdn"]}, {"stages": ["m.login.msisdn", "m.login.email.identity"]}]}
  • Token Request
  • A POST call to _matrix/client/r0/register/email/requestToken where a secret is specified and a SID is returned.
curl "https://comms.secfirst.org/_matrix/client/r0/register/email/requestToken" --data-binary '{"email":"klaidliadon+test@gmail.com","client_secret":"g2mmk6jo4oFWQ5bi0CcUnkFfZT1u8RMu","send_attempt":1,"next_link":"https://riot.im/app/#/register?client_secret=g2mmk6jo4oFWQ5bi0CcUnkFfZT1u8RMu&hs_url=https%3A%2F%2Fcomms.secfirst.org&is_url=https%3A%2F%2Fvector.im&session_id=vtnimoEKSQyYOTqhKiqpOXHi","id_server":"vector.im"}'
  • Token Verification - A POST call to the identity server (vector.im) to validate the token received via email.
https://vector.im/_matrix/identity/api/v1/validate/email/submitToken?token=beT0V1xZlWxuXCVkF06BTnIp1ljuUJQX&client_secret=g2mmk6jo4oFWQ5bi0CcUnkFfZT1u8RMu&sid=245592

For our use case we can implement our own token request/verification.

The client sends Email, Client secret, Client organisation, signed with a JWT.

The server receives the message and verify the signature using the app public key.

It creates a new token for this request and stores it, then sends an email with a link containing all the data, plus the token, always signed.

The link will be intercepted by the app that will verify the signature and make another two signed requests to verify the user email and add him to the organisation. For this scenario it will be useful to have an organisation table containing:

  • Organisation package/app (org.secfirst.umbrella)
  • The URL format with placeholders for point 3 (umbrella://action/{1})

Endpoints

Organisation creation

This endpoint should be used only by the server administrator so it must be protected. Creates a Org record with

  • Org name
  • Package id
  • Admin email
  • App intent/action format
  • Verification hash and sends a link to the Admin email containing the hash. The link will be a intent/action (for instance umbrella://account/new?vefication=xxxx&email=xxxxxx) so that it gets intercepted by the app. The hash should be created with email address

Admin creation

The intent created opens a form for inserting username and password (twice) plus a phone number ( if we want 2FA). The app calls the endpoint providing:

  • Username
  • Password
  • Email
  • Phone
  • Verification hash

The server verifies the hash over the email and if that’s okay it creates the user and the 3pid email record. If the server can send sms, a token can be requested for the phone verification. The idea is to merge /_matrix/client/r0/register e _matrix/client/r0/register/email/requestToken to check the hash first then executing both and return the register result.

Separate tables for notifications and groups will be used, Matrix for identities, write directly to db, use PostgreSQL which is supported by Matrix.

Clone this wiki locally