docs: add docs for flows and all stages

docs/Dockerfile

@@ -1,14 +0,0 @@
-FROM python:3.8-slim-buster as builder
-
-WORKDIR /mkdocs
-
-RUN pip install mkdocs mkdocs-material
-
-COPY docs/ docs
-COPY mkdocs.yml .
-
-RUN mkdocs build
-
-FROM nginx
-
-COPY --from=builder /mkdocs/site /usr/share/nginx/html

docs/build.sh

@@ -0,0 +1,3 @@
+#!/bin/bash -x
+pip install -U mkdocs mkdocs-material
+mkdocs gh-deploy

docs/flow/stages/email/email.md

@@ -0,0 +1,5 @@
+# E-Mail
+
+This stage can be used for E-Mail verification. passbook's background worker will send an E-Mail using the specified connection details. When an E-Mail can't be delivered, it is automatically periodically retried.
+
+![](email-recovery.png)

docs/flow/stages/identification/identification.md

@@ -0,0 +1,25 @@
+# Identification
+
+This stage provides a ready-to-go form for users to identify themselves.
+
+## Options
+
+### User Fields
+
+Select which fields the user can use to identify themselves. Multiple fields can be specified and separated with a comma.
+Valid choices:
+
+- email
+- username
+
+### Template
+
+This specifies which template is rendered. Currently there are two templates.
+
+The `Login` template shows configured Sources below the login form, as well as linking to the defined Enrollment and Recovery flows.
+
+The `Recovery` template shows only the form.
+
+### Enrollment/Recovery Flow
+
+These fields specify if and which flows are linked on the form. The enrollment flow is linked as `Need an account? Sign up.`, and the recovery flow is linked as `Forgot username or password?`.

docs/flow/stages/invitation/invitation.md

@@ -0,0 +1,7 @@
+# Invitation Stage
+
+This stage can be used to invite users. You can use this enroll users with preset values.
+
+If the option `Continue Flow without Invitation`, this stage will continue when no invitation token is present.
+
+If you want to check if a user has used an invitation within a policy, you can check `request.context.invitation_in_effect`.

docs/flow/stages/otp/otp.md

@@ -0,0 +1,7 @@
+# OTP Stage
+
+This stage offers a generic Time-based One-time Password authentication step.
+
+You can optionally enforce this step, which will force every user without OTP setup to configure it.
+
+This stage uses a 6-digit Code with a 30 second time-drift. This is currently not changeable.

docs/flow/stages/password/password.md

@@ -0,0 +1,3 @@
+# Password Stage
+
+This is a generic password prompt, which authenticates the currently `pending_user`. This stage allows the selection of the Backend the user is authenticated against.

docs/flow/stages/prompt/prompt.md

@@ -0,0 +1,42 @@
+# Prompt Stage
+
+This stage is used to show the user arbitrary prompts.
+
+## Prompt
+
+The prompt can be any of the following types:
+
+|          |                                                                  |
+|----------|------------------------------------------------------------------|
+| text     | Arbitrary text, no client-side validation is done.               |
+| email    | E-Mail input, requires a valid E-Mail adress                     |
+| password | Password Input                                                   |
+| number   | Number Input, any number is allowed                              |
+| checkbox | Simple Checkbox                                                  |
+| hidden   | Hidden Input field, allows for the pre-setting of default values |
+
+A Prompt has the following attributes:
+
+### `field_key`
+
+HTML name used for the prompt. This key is also used to later retrieve the data in expression policies:
+
+```jinja2
+{{ request.context.prompt_data.<field_key> }}
+```
+
+### `label`
+
+Label used to describe the Field. This might not be shown depending on the template selected.
+
+### `required`
+
+Flag that decides whether or not this field is required.
+
+### `placeholder`
+
+Field placeholder, shown within the input field. This field is also used by the `hidden` type as the actual value.
+
+### `order`
+
+Numerical index of the prompt. This applies to all stages this prompt is a part of.

docs/flow/stages/prompt/validation.md

@@ -0,0 +1,17 @@
+# Prompt Validation
+
+Further validation of prompts can be done using policies.
+
+To validate that two password fields are identical, create the following expression policy:
+
+```jinja2
+{% if request.context.prompt_data.password == request.context.prompt_data.password_repeat %}
+True
+{% else %}
+{% do pb_message("Passwords don't match.") %}
+False
+{% endif %}
+```
+This policy expects you two have two password fields with `field_key` set to `password` and `password_repeat`.
+
+Afterwards bind this policy to the prompt stage you want to validate.

docs/flow/stages/user_delete.md

@@ -0,0 +1,8 @@
+# User Delete Stage
+
+!!! danger
+    This stage deletes the `pending_user` without any confirmation. You have to make sure the user is aware of this.
+
+This stage is intended for an unenrollment flow. It deletes the currently pending user.
+
+The pending user is also removed from the current session.

docs/flow/stages/user_login.md

@@ -0,0 +1,5 @@
+# User Login Stage
+
+This stage attaches a currently pending user to the current session.
+
+It can be used after `user_write` during an enrollment flow, or after a `password` stage during an authentication flow.

docs/flow/stages/user_logout.md

@@ -0,0 +1,3 @@
+# User Logout Stage
+
+Opposite stage of [User Login Stages](user_login.md). It removes the user from the current session.

docs/flow/stages/user_write.md

@@ -0,0 +1,3 @@
+# User Write Stage
+
+This stages writes data from the current context to the current pending user. If no user is pending, a new one is created.

docs/k8s/deployment.yml

@@ -1,33 +0,0 @@
----
-apiVersion: apps/v1beta2
-kind: Deployment
-metadata:
-  name: passbook-docs
-  namespace: prod-passbook-docs
-  labels:
-    app.kubernetes.io/name: passbook-docs
-    app.kubernetes.io/managed-by: passbook-docs
-spec:
-  replicas: 1
-  selector:
-    matchLabels:
-      app.kubernetes.io/name: passbook-docs
-  template:
-    metadata:
-      labels:
-        app.kubernetes.io/name: passbook-docs
-    spec:
-      containers:
-        - name: passbook-docs
-          image: "beryju/passbook-docs:latest"
-          ports:
-            - name: http
-              containerPort: 80
-              protocol: TCP
-          resources:
-            limits:
-              cpu: 10m
-              memory: 20Mi
-            requests:
-              cpu: 10m
-              memory: 20Mi

docs/k8s/ingress.yml

@@ -1,21 +0,0 @@
----
-apiVersion: extensions/v1beta1
-kind: Ingress
-metadata:
-  labels:
-    app.kubernetes.io/name: passbook-docs
-  name: passbook-docs
-  namespace: prod-passbook-docs
-spec:
-  rules:
-    - host: docs.passbook.beryju.org
-      http:
-        paths:
-          - backend:
-              serviceName: passbook-docs-http
-              servicePort: http
-            path: /
-  tls:
-    - hosts:
-        - docs.passbook.beryju.org
-      secretName: passbook-docs-acme

docs/k8s/service.yml

@@ -1,17 +0,0 @@
----
-apiVersion: v1
-kind: Service
-metadata:
-  name: passbook-docs-http
-  namespace: prod-passbook-docs
-  labels:
-    app.kubernetes.io/name: passbook-docs
-spec:
-  type: ClusterIP
-  ports:
-    - port: 80
-      targetPort: http
-      protocol: TCP
-      name: http
-  selector:
-    app.kubernetes.io/name: passbook-docs

mkdocs.yml

@@ -12,11 +12,12 @@ nav:
       - Captcha Stage: flow/stages/captcha/captcha.md
       - Dummy Stage: flow/stages/dummy/dummy.md
       - E-Mail Stage: flow/stages/email/email.md
-      - Identification Stage: flow/stages/identification.md
-      - Invitation Stage: flow/stages/invitation.md
-      - OTP Stage: flow/stages/otp.md
-      - Password Stage: flow/stages/password.md
-      - Prompt Stage: flow/stages/prompt.md
+      - Identification Stage: flow/stages/identification/identification.md
+      - Invitation Stage: flow/stages/invitation/invitation.md
+      - OTP Stage: flow/stages/otp/otp.md
+      - Password Stage: flow/stages/password/password.md
+      - Prompt Stage: flow/stages/prompt/prompt.md
+      - Prompt Stage Validation: flow/stages/prompt/validation.md
       - User Delete Stage: flow/stages/user_delete.md
       - User Login Stage: flow/stages/user_login.md
       - User Logout Stage: flow/stages/user_logout.md

passbook/stages/invitation/stage.py

@@ -7,6 +7,7 @@ from passbook.stages.invitation.models import Invitation, InvitationStage
 from passbook.stages.prompt.stage import PLAN_CONTEXT_PROMPT
 
 INVITATION_TOKEN_KEY = "token"
+INVITATION_IN_EFFECT = "invitation_in_effect"
 
 
 class InvitationStageView(StageView):
@@ -23,4 +24,5 @@ class InvitationStageView(StageView):
         token = request.GET[INVITATION_TOKEN_KEY]
         invite: Invitation = get_object_or_404(Invitation, pk=token)
         self.executor.plan.context[PLAN_CONTEXT_PROMPT] = invite.fixed_data
+        self.executor.plan.context[INVITATION_IN_EFFECT] = True
         return self.executor.stage_ok()