From ad01e4f0bbae8933c897980391e36e866670dc1e Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sun, 30 Dec 2018 21:46:54 +0200 Subject: Change: update arch doc --- architecture.mdwn | 122 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 116 insertions(+), 6 deletions(-) diff --git a/architecture.mdwn b/architecture.mdwn index a071214..b9cd2c7 100644 --- a/architecture.mdwn +++ b/architecture.mdwn @@ -55,10 +55,28 @@ guarantees the token comes from Qvisqve. To prevent the access token from leaking to the browser, effiweb keeps the token, and also manages user sessions. +Since it is impractical to give each member a password, in a secure +manner, Effireg will instead allow a member to request a unique, +single-use login link to be emailed to them. The link will take the +member's web browser to effiweb, which will extract a unique token +from the link, and use that to authenticate the member for Qvisqve, +and start a new session. As long as the session exist (until the +member logs out), they can use the effiweb application. + +(A valied-until-logout session, without timeouts, is not ideal from a +security perspective, but given the harm of an un-privileged member's +hijacked session is minor, it's good enough. When Effireg develops +further and the potential harm become bigger, session timeout will be +implemented.) + Non-interactive API clients are authenticated using the [OAuth2][] protocol, specifically using client credential grants. This also provides an access token, similar to the one from end-user -authentication. +authentication. API clients will not be available to normal members at +this time, only members trusted by the board. + +Regardless of trust level, each member and API client will have a set +of allowed operations that constrain what they can do. # Data model @@ -73,6 +91,10 @@ supported: ## Subject resource + { + "username": "007@mi6.example.com" + } + A subject resource has the following fields: * `username` — the username of the subject; this can change, the @@ -80,11 +102,25 @@ A subject resource has the following fields: not by the username The subject resource does not have any data that isn't needed for -end-user identification. Effiapi manages and Qvisqve uses the subject -resource. Effiapi does not expose it via its own API. +end-user identification. Effiapi manages the subject resource via the +Qvisqve API. Effiapi does not expose it via its own API. + +To allow members to log using their email address, the username is set +to their primary email address. ## Password resource + { + "subject-id": "abcdef0123456789#, + "version": 1, + "hash": "xxxxx", + "salt": "yyyyy", + "key_len": 128, + "p": 1, + "r": 8, + "N": 16384 + } + A password resource has the following fields: * `subject_id` — resource id of the subject whose password this @@ -98,15 +134,25 @@ A password resource has the following fields: * `r` — parameter for scrypt * `p` — parameter for scrypt -Effiapi manages and Qvisqve uses the password resource. Effiapi does -not expose it via its own API. +Effiapi manages the password resource via the Qvisqve API. Effiapi +does not expose it via its own API. + ## Member resource (memb) + + + { + "subject-id": "abcdef0123456789", + "fullname": "James Bond", + "primary-email": "007@mi6.example.com", + "years-paid": [2010, 2011, 2012, 2018] + } A membership resource has the following fields: * `subject-id` — the resource id of the subject resource for - the member + the member; this is assigned by effiapi (really Muck), when the + resource is created, and can't be changed via the API * `fullname` — the full name of the member * `primary-email` — the primary email address for the member (and currently the only one) @@ -115,3 +161,67 @@ A membership resource has the following fields: Effiapi manages and uses the memb resource, and exposes it via its own API. Effiweb renders it for the user. + +# API + +The effiapi API is a RESTful, HTTP-based API using JSON. The only +resource exposed is `memb`, via the `/memb` +endpoint. The following operations are defined: + +* `POST /memb` — create a new member resource; this implicitly + creates the subject resource as well, allowing the member to log in; + the `subject-id` field is ignored, if set +* `PUT /memb` — update an existing member resource; the whole + resource is updated, not just selected fields +* `GET /memb` — retrieve a member resource; the whole + resource is returned + +In all responses, the following headers convey metadata about the +resource: + +* `Muck-Id` — the internal, random identifier for the resource, + assigned by the API +* `Muck-Revision` — the current revision of the resource + +`GET` requests must use the `Muck-Id` header to specify which member +resource is to be retrieved. + +`PUT` requests must use the `Muck-Id` header, and also the the +`Muck-Revision` header, with the value showing the **current** +revision. This prevents concurrent updates from updating with +conflicting data. + +`PUT` is not allowed to change the `subject-id` field of a member +resource. + +## Search language for members + +In addition to managing individual member resources, the API provides +a search function. Note that there is no way to list member resources; +a search that matches all can be used instead. + +* `GET /search` — search for member resources matching the + required criteria; the search language is described below + +The search request body should look like this: + + { + "where": "data", + "field": "email", + "pattern": "007@mi6.example.com", + "op": "==" + } + +A search may return any number of results: + + { + "resources": ["abcdef0123456789", "cafef00d"] + } + +It is the API client's (effiweb's) responsibility to retrieve the +resources given the id, and to do any more detailed selecting among +the resources. It is only possible to search based on fields that are +at the top level, and have a string value. + +The search will only match, and return, resources that the user is +allowed to see. -- cgit v1.2.1