From 13876d39226b7c1b9d40a165ce9393d2a018e7f6 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sun, 30 Dec 2018 19:43:12 +0200 Subject: Change: drop docs, keep yarns --- doc/000.yarn | 172 --------------------------------------------------------- doc/Makefile | 7 --- doc/arch.css | 15 ----- doc/arch.diag | 12 ---- doc/build.sh | 14 ----- effitool.log | 12 ++++ yarns/000.yarn | 52 +++++++++++++++++ 7 files changed, 64 insertions(+), 220 deletions(-) delete mode 100644 doc/000.yarn delete mode 100644 doc/Makefile delete mode 100644 doc/arch.css delete mode 100644 doc/arch.diag delete mode 100755 doc/build.sh create mode 100644 effitool.log create mode 100644 yarns/000.yarn diff --git a/doc/000.yarn b/doc/000.yarn deleted file mode 100644 index 2bfff88..0000000 --- a/doc/000.yarn +++ /dev/null @@ -1,172 +0,0 @@ ---- -title: Effireg architecture -author: Lars Wirzenius -... - -# Introduction - -Effireg is a web-based membership register for the Effi non-profit -association. See for more information about Effi. - -Effireg is written for Effi, but it is free software, released under -the Affero GPL v3 license, and may be used by others. No guarantees of -quality. - -# Architecture overview - -## Assumptions - -The architecture has been designed under the following assumptions: - -* Privacy is important, and should be the default. People should only - have access to the information they are authorized to access. - -* Members should be able to see their own information, without having - to go through the Effi membership register admin. - -* It's not practical to have every member have a password. - Authentication can be done by sending the member a unique, - single-use link when they want to log in. - -## Components - -![Architectural components](arch.png) - -Effireg consists of four main components: - -* **effiapi** provides a RESTful HTTP API for managing the membership - data, and for doing things with or to the data. All operations go - via the API. - -* **effiweb** provides the frontend for the web application to use the - membership register. It renders HTML to the user, is accesses via a - web browser, and generally is the user-visible part of Effireg. - -* **Qvisqve** provides authentication of end-users (the members, and - admins). It lets users log in, and keeps track of what each user is - allowed to do. - -* **Muck-POC** stores the actual membership register data, and - controls access to it, based on access tokens from Qvisqve. - -## Authentication - -[OpenID Connect]: https://openid.net/specs/openid-connect-core-1_0.html -[OAuth2]: https://oauth.net/2/ - -End-users are authenticated using the [OpenID Connect][] protocol, -specifically the authorization code flow. In this flow, Qvisqve -provides cryptographically signed access tokens, which identify the -user and specify a list of things the user may do. The signature -guarantees the token comes from Qvisqve. - -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. - -# Data model - -The membership register stores data as "resources" in Muck-POC. Each -resource is a JSON object. The following types of objects are -supported: - -* **subject** represents a person who is allowed to use the register; - it it used to identify the user for authentication -* **password** stores the encrypted password for a subject -* **memb** represets a subject's membership in Effi - -### Subject resource - -A subject resource has the following fields: - -* `username` — the username of the subject; this can change, the - subject is identified by the resource identifier in the register, - 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. - -### Password resource - -A password resource has the following fields: - -* `subject_id` — resource id of the subject whose password this - is -* `version` — version of the password resource (identifies - algorithm); must be 1 -* `hash` — the password, encrypted with the scrypt algorithm -* `salt` — a random string to prevent dictionary attacks -* `key_len` — parameter for scrypt -* `N` — parameter for scrypt -* `r` — parameter for scrypt -* `p` — parameter for scrypt - -Effiapi manages and Qvisqve uses the password resource. - -### Member resource (memb) - -A membership resource has the following fields: - -* `subject-id` — the resource id of the subject resource for - the member -* `fullname` — the full name of the member -* `primary-email` — the primary email address for the member - (and currently the only one) -* `years-paid` — list of integers for the years for which the - member has paid their membership - -Effiapi manages and uses the memb resource. Effiweb renders it for the -user. - -# effiapi - -[yarn]: https://liw.fi/cmdtest/ - -This chapter descibes the effiapi API, as a [yarn][] automated -scenario test. It is meant to be understandable to Effi sysadmins, as -well as be an executable test suite for the API. - -The API is a simple RESTful HTTP API using JSON. This means that: - -* each API call is an HTTP request, with a response - -* all data is represented as JSON in the body of the request of - response - -* metadata about the data is represeneted as HTTP headers - -* standard HTTP verbs (POST, PUT, GET, DELETE) are used to indicate - the action - -* standard HTTP status codes are used to indicate result of the - request (200 = OK, 404 = not found, etc) - -## Manage memberships - -This section shows the API calls to manage a memberhip: to create the -member, to update and retrieve it, and to search memberships. - -~~~ -SCENARIO Manage memberships - -GIVEN An effiapi instance -WHEN admin requests POST /memb with body { "fullname": "James Bond" } -THEN the member id is ID - -WHEN admin requests GET /memb with header Muck-Id: ${ID} -THEN HTTP status 200 -AND HTTP body matches { "fullname": "James Bond" } -~~~ - -TODO: - -* update -* delete -* search -* members can see their own data, and can't see each others' -* member follows authn link emailed to them - -# Appendix: Yarn scenario step implementations - diff --git a/doc/Makefile b/doc/Makefile deleted file mode 100644 index 14078f5..0000000 --- a/doc/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -yarns = $(wildcard *.yarn) -images = $(wildcard *.diag) - -all: arch.html - -arch.html: $(yarns) $(images) arch.css - ./build.sh diff --git a/doc/arch.css b/doc/arch.css deleted file mode 100644 index 25720b2..0000000 --- a/doc/arch.css +++ /dev/null @@ -1,15 +0,0 @@ -html { - font-family: serif; - margin-left: 4em; - margin-right: 4em; -} - -h1, h2, h3 { - font-family: sans-serif; - margin-top: 2em; -} - - -h1 { font-size: 3em; } -h2 { font-size: 2em; } -h3 { font-size: 1em; } diff --git a/doc/arch.diag b/doc/arch.diag deleted file mode 100644 index d1e0f1e..0000000 --- a/doc/arch.diag +++ /dev/null @@ -1,12 +0,0 @@ -blockdiag { - browser; - qvisqve; - effiweb; - effiapi; - muck; - - browser -> effiweb; - browser -> qvisqve; - effiweb -> effiapi; - effiapi -> muck; -} diff --git a/doc/build.sh b/doc/build.sh deleted file mode 100755 index 8a04877..0000000 --- a/doc/build.sh +++ /dev/null @@ -1,14 +0,0 @@ -#!/bin/sh - -set -eu - -version="$(git describe --dirty)" -blockdiag3 arch.diag -pandoc \ - -Vdate="Version: $version" \ - --toc \ - --standalone \ - --self-contained \ - --css arch.css \ - -o arch.html \ - *.yarn diff --git a/effitool.log b/effitool.log new file mode 100644 index 0000000..7033c68 --- /dev/null +++ b/effitool.log @@ -0,0 +1,12 @@ +2018-11-23 20:31:28,222 INFO Effitool starts +2018-11-23 20:31:28,222 DEBUG calling 'add_member' with {'url': 'https://effi-reg.vm.liw.fi', 'token': None, 'token_url': 'https://effi-reg.vm.liw.fi', 'client_id': 'admin', 'client_secret': 'hunter2', 'logfile': 'effitool.log', 'fake': False, 'username': 'tomjon', 'member': 'tomjon.yaml'} +2018-11-23 20:31:28,236 DEBUG Starting new HTTPS connection (1): effi-reg.vm.liw.fi:443 +2018-11-23 20:31:28,523 DEBUG https://effi-reg.vm.liw.fi:443 "POST /token HTTP/1.1" 200 983 +2018-11-23 20:31:28,525 INFO Add member tomjon: {'fullname': 'Tomjon of Lancre', 'birthday': '1969-09-01', 'address': 'Palace\nLancre\nRamtom mountains\nDiscworld\n', 'home_council': 'Lancre', 'residence_country': 'Lancre', 'primary_email_address': 'tomjon@example.com', 'primary_email_address_tested_dates': ['2018-11-24'], 'secondary_email_address': 'tomjon@genua.example.com', 'secondary_email_address_tested_dates': ['2018-01-01'], 'membership_type': 'annual', 'membership_years': [2017, 2018], 'membership_years_paid': [2017, 2018], 'membership_years_not_paid': [2019], 'mailing_lists': ['effi-aktivistit@listat.effi.org']} +2018-11-23 20:31:28,567 DEBUG https://effi-reg.vm.liw.fi:443 "POST /mem HTTP/1.1" 201 580 +2018-11-23 20:31:33,082 INFO Effitool starts +2018-11-23 20:31:33,082 DEBUG calling 'add_member' with {'url': 'https://effi-reg.vm.liw.fi', 'token': None, 'token_url': 'https://effi-reg.vm.liw.fi', 'client_id': 'admin', 'client_secret': 'hunter2', 'logfile': 'effitool.log', 'fake': False, 'username': 'verence', 'member': 'verence.yaml'} +2018-11-23 20:31:33,093 DEBUG Starting new HTTPS connection (1): effi-reg.vm.liw.fi:443 +2018-11-23 20:31:33,251 DEBUG https://effi-reg.vm.liw.fi:443 "POST /token HTTP/1.1" 200 984 +2018-11-23 20:31:33,253 INFO Add member verence: {'fullname': 'Verence of Lancre', 'birthday': '1969-09-01', 'address': 'Palace\nLancre\nRamtom mountains\nDiscworld\n', 'home_council': 'Lancre', 'residence_country': 'Lancre', 'primary_email_address': 'verence@example.com', 'primary_email_address_tested_dates': ['2018-11-24'], 'secondary_email_address': 'verence@genua.example.com', 'secondary_email_address_tested_dates': ['2018-01-01'], 'membership_type': 'annual', 'membership_years': [2017, 2018], 'membership_years_paid': [2017, 2018], 'membership_years_not_paid': [2019], 'mailing_lists': ['effi-aktivistit@listat.effi.org']} +2018-11-23 20:31:33,286 DEBUG https://effi-reg.vm.liw.fi:443 "POST /mem HTTP/1.1" 201 583 diff --git a/yarns/000.yarn b/yarns/000.yarn new file mode 100644 index 0000000..9bd0432 --- /dev/null +++ b/yarns/000.yarn @@ -0,0 +1,52 @@ +--- +title: Effiapi test suite +author: Lars Wirzenius +... + +# Test scenarios + +This chapter descibes the effiapi API, as a [yarn][] automated +scenario test. It is meant to be understandable to Effi sysadmins, as +well as be an executable test suite for the API. + +The API is a simple RESTful HTTP API using JSON. This means that: + +* each API call is an HTTP request, with a response + +* all data is represented as JSON in the body of the request of + response + +* metadata about the data is represeneted as HTTP headers + +* standard HTTP verbs (POST, PUT, GET, DELETE) are used to indicate + the action + +* standard HTTP status codes are used to indicate result of the + request (200 = OK, 404 = not found, etc) + +## Manage memberships + +This section shows the API calls to manage a memberhip: to create the +member, to update and retrieve it, and to search memberships. + +~~~ +SCENARIO Manage memberships + +GIVEN An effiapi instance +WHEN admin requests POST /memb with body { "fullname": "James Bond" } +THEN the member id is ID + +WHEN admin requests GET /memb with header Muck-Id: ${ID} +THEN HTTP status 200 +AND HTTP body matches { "fullname": "James Bond" } +~~~ + +TODO: + +* update +* delete +* search +* members can see their own data, and can't see each others' +* member follows authn link emailed to them + +# Appendix: Yarn scenario step implementations -- cgit v1.2.1