summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLars Wirzenius <liw@liw.fi>2018-12-30 21:46:54 +0200
committerLars Wirzenius <liw@liw.fi>2018-12-30 21:46:54 +0200
commitad01e4f0bbae8933c897980391e36e866670dc1e (patch)
tree74bb41424c2cef578175c05275f935b19aa548f8
parent2ad310451b3794f0ad95950ad1f5dca4926a8382 (diff)
downloadeffireg-website-ad01e4f0bbae8933c897980391e36e866670dc1e.tar.gz
Change: update arch doc
-rw-r--r--architecture.mdwn122
1 files 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` &mdash; 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` &mdash; resource id of the subject whose password this
@@ -98,15 +134,25 @@ A password resource has the following fields:
* `r` &mdash; parameter for scrypt
* `p` &mdash; 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.
+<a name="memb">
## Member resource (memb)
+</a>
+
+ {
+ "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` &mdash; 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` &mdash; the full name of the member
* `primary-email` &mdash; 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 <a href="#memb">`memb`</a>, via the `/memb`
+endpoint. The following operations are defined:
+
+* `POST /memb` &mdash; 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` &mdash; update an existing member resource; the whole
+ resource is updated, not just selected fields
+* `GET /memb` &mdash; retrieve a member resource; the whole
+ resource is returned
+
+In all responses, the following headers convey metadata about the
+resource:
+
+* `Muck-Id` &mdash; the internal, random identifier for the resource,
+ assigned by the API
+* `Muck-Revision` &mdash; 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` &mdash; 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.