docs: add docs for flows, start docs for stages

README.md

@@ -1,4 +1,4 @@
-# passbook
+<img src="passbook/static/static/passbook/logo.svg" height="50" alt="passbook logo"><img src="passbook/static/static/passbook/brand_inverted.svg" height="50" alt="passbook">
 
 ![](https://img.shields.io/github/workflow/status/beryju/passbook/passbook-ci?style=flat-square)
 ![](https://img.shields.io/docker/pulls/beryju/passbook.svg?style=flat-square)

docs/factors.md

@@ -1,23 +0,0 @@
-# Factors
-
-A factor represents a single authenticating factor for a user. Common examples of this would be a password or an OTP. These factors can be combined in any order, and can be dynamically enabled using policies.
-
-## Password Factor
-
-This is the standard Password Factor. It allows you to select which Backend the password is checked with. here you can also specify which Policies are used to check the password. You can also specify which Factors a User has to pass to recover their account.
-
-## Dummy Factor
-
-This factor waits a random amount of time. Mostly used for debugging.
-
-## E-Mail Factor
-
-This factor is mostly for recovery, and used in conjunction with the Password Factor.
-
-## OTP Factor
-
-This is your typical One-Time Password implementation, compatible with Authy and Google Authenticator. You can enfore this Factor so that every user has to configure it, or leave it optional.
-
-## Captcha Factor
-
-While this factor doesn't really authenticate a user, it is part of the Authentication Flow. passbook uses Google's reCaptcha implementation.

docs/flow/flows.md

@@ -0,0 +1,45 @@
+# Flows
+
+Flows are a method of describing a sequence of stages. A stage represents a single verification or logic step. They are used to authenticate users, enroll them, and more.
+
+Upon Flow execution, a plan is generated, which contains all stages. This means upon execution, all attached policies are evaluated. This behaviour can be altered by enabling the `Re-evaluate Policies` option on the binding.
+
+To determine which flow is linked, passbook searches all Flows with the required designation and chooses the first instance the current user has access to.
+
+## Permissions
+
+Flows can have policies assigned to them, which determines if the current user is allowed to see and use this flow.
+
+## Designation
+
+Flows are designated for a single Purpose. This designation changes when a Flow is used. The following designations are available:
+
+### Authentication
+
+This is designates a flow to be used for authentication.
+
+The authentication flow should always contain a `user_login` stage, which attaches the staged user to the current session.
+
+### Invalidation
+
+This designates a flow to be used for the invalidation of a session.
+
+This stage should always contain a `user_logout` stage, which resets the current session.
+
+### Enrollment
+
+This designates a flow for enrollment. This flow can contain any amount of Prompt stages, E-Mail verification or Captchas. At the end to create the user, you can use the `user_write` stage, which either updates the currently staged user, or if none exists, creates a new one.
+
+### Unenrollment
+
+This designates a flow for unenrollment. This flow can contain any amount of verification, like `email` or captcha. To finally delete the account, use the `user_delete` stage.
+
+### Recovery
+
+This designates a flow for recovery. This flow normally contains an `identification` stage to find the user. Then it can contain any amount of verification, like `email` or captcha.
+Afterwards, use the `prompt` stage to ask the user for a new password and use `user_write` to update the password.
+
+### Change Password
+
+This designates a flow for password changing. This flow can contain any amount of verification, like `email` or captcha.
+Afterwards, use the `prompt` stage to ask the user for a new password and use `user_write` to update the password.

docs/flow/stages/captcha/captcha.md

@@ -0,0 +1,7 @@
+# Captcha stage
+
+This stage adds a form of verification using [Google's ReCaptcha](https://www.google.com/recaptcha/intro/v3.html).
+
+This stage has two required fields. You need a Public and a Private key, both of which you can acquire at https://www.google.com/recaptcha/admin.
+
+![](captcha-admin.png)

docs/flow/stages/dummy/dummy.md

@@ -0,0 +1,5 @@
+# Dummy stage
+
+This stage is used for development, and has no function. It presents the User with a form, that requires a single confirmation.
+
+![](dummy.png)

docs/installation/install.md

@@ -1,6 +0,0 @@
-# Installation
-
-There are two supported ways to install passbook:
-
--   [docker-compose](docker-compose.md) for test- or small productive setups
--   [Kubernetes](./kubernetes.md) for larger Productive setups

mkdocs.yml

@@ -5,16 +5,28 @@ copyright: "Copyright © 2019 - 2020 BeryJu.org"
 nav:
   - Home: index.md
   - Installation:
-    - Installation: installation/install.md
     - docker-compose: installation/docker-compose.md
     - Kubernetes: installation/kubernetes.md
+  - Flows: flow/flows.md
+  - Stages:
+      - 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
+      - User Delete Stage: flow/stages/user_delete.md
+      - User Login Stage: flow/stages/user_login.md
+      - User Logout Stage: flow/stages/user_logout.md
+      - User Write Stage: flow/stages/user_write.md
   - Sources: sources.md
   - Providers: providers.md
   - Property Mappings:
     - Overview: property-mappings/index.md
     - Reference:
       - User Object: property-mappings/reference/user-object.md
-  - Factors: factors.md
   - Policies:
     - Overview: policies/index.md
     - Expression: policies/expression/index.md

passbook/flows/forms.py

@@ -44,6 +44,9 @@ class FlowStageBindingForm(forms.ModelForm):
             "re_evaluate_policies",
             "order",
         ]
+        labels = {
+            "re_evaluate_policies": _("Re-evaluate Policies"),
+        }
         widgets = {
             "name": forms.TextInput(),
         }

passbook/stages/email/forms.py

@@ -34,6 +34,7 @@ class EmailStageForm(forms.ModelForm):
         widgets = {
             "name": forms.TextInput(),
             "host": forms.TextInput(),
+            "subject": forms.TextInput(),
             "username": forms.TextInput(),
             "password": forms.TextInput(),
         }

passbook/stages/email/stage.py

@@ -46,6 +46,9 @@ class EmailStageView(FormView, StageView):
         return super().get(request, *args, **kwargs)
 
     def form_invalid(self, form: EmailStageSendForm) -> HttpResponse:
+        if PLAN_CONTEXT_PENDING_USER not in self.executor.plan.context:
+            messages.error(self.request, _("No pending user."))
+            return super().form_invalid(form)
         pending_user = self.executor.plan.context[PLAN_CONTEXT_PENDING_USER]
         valid_delta = timedelta(
             minutes=self.executor.current_stage.token_expiry + 1

passbook/static/static/passbook/brand_inverted.svg

@@ -0,0 +1,2 @@
+<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+  width="120px" height="20px" viewBox="15 0 10 10" enable-background="new 0 0 270 10" xml:space="preserve"><defs><style>.cls-1{isolation:isolate;}.cls-2{fill:#000;}</style></defs><g class="cls-1"><path class="cls-2" d="M1.65,11V2.45H2.87V3a2.81,2.81,0,0,1,.47-.45A1.13,1.13,0,0,1,4,2.38,1.11,1.11,0,0,1,5.1,3a1.55,1.55,0,0,1,.16.5,5.61,5.61,0,0,1,0,.81V6.58c0,.45,0,.77,0,1a1.17,1.17,0,0,1-.55.9,1.23,1.23,0,0,1-.7.16,1.35,1.35,0,0,1-.64-.16A1.53,1.53,0,0,1,2.89,8h0v3ZM4.08,4.43a1.21,1.21,0,0,0-.14-.6.51.51,0,0,0-.46-.22A.54.54,0,0,0,3,3.82a.8.8,0,0,0-.17.54V6.73A.68.68,0,0,0,3,7.2a.6.6,0,0,0,.44.18A.53.53,0,0,0,4,7.17a1,1,0,0,0,.12-.5Z"/><path class="cls-2" d="M8.63,8.54V7.91h0a2.24,2.24,0,0,1-.48.52,1.13,1.13,0,0,1-.69.18A1.39,1.39,0,0,1,7,8.54a1.09,1.09,0,0,1-.43-.24,1.32,1.32,0,0,1-.33-.49A2.33,2.33,0,0,1,6.11,7a4.89,4.89,0,0,1,.08-.91,1.51,1.51,0,0,1,.31-.65,1.44,1.44,0,0,1,.59-.38A3.19,3.19,0,0,1,8,4.93h.59V4.33a1,1,0,0,0-.13-.52A.52.52,0,0,0,8,3.61a.71.71,0,0,0-.44.15.78.78,0,0,0-.26.46H6.13A2,2,0,0,1,6.69,2.9a1.73,1.73,0,0,1,.57-.38A2,2,0,0,1,8,2.38a2.18,2.18,0,0,1,.72.12,1.71,1.71,0,0,1,.59.36,2,2,0,0,1,.38.6,2.18,2.18,0,0,1,.14.84V8.54Zm0-2.62-.34,0a1.2,1.2,0,0,0-.67.18.76.76,0,0,0-.29.68.89.89,0,0,0,.17.56A.55.55,0,0,0,8,7.53a.63.63,0,0,0,.49-.2.91.91,0,0,0,.17-.58Z"/><path class="cls-2" d="M13,4.16a.59.59,0,0,0-.2-.47.65.65,0,0,0-.42-.16.59.59,0,0,0-.45.19.66.66,0,0,0-.15.43.8.8,0,0,0,.08.33.85.85,0,0,0,.44.29l.71.29a1.73,1.73,0,0,1,.95.72,2,2,0,0,1,.26,1,1.85,1.85,0,0,1-.52,1.3,1.56,1.56,0,0,1-.58.39,1.88,1.88,0,0,1-2-.32,1.58,1.58,0,0,1-.4-.57,1.81,1.81,0,0,1-.17-.8h1.15a1.11,1.11,0,0,0,.17.47.56.56,0,0,0,.49.22.71.71,0,0,0,.47-.18A.59.59,0,0,0,13,6.8a.69.69,0,0,0-.13-.43,1.08,1.08,0,0,0-.48-.32l-.59-.21a2.08,2.08,0,0,1-.9-.64,1.66,1.66,0,0,1-.33-1,1.89,1.89,0,0,1,.14-.72,1.78,1.78,0,0,1,.4-.57,1.5,1.5,0,0,1,.56-.36,1.82,1.82,0,0,1,.7-.13,1.93,1.93,0,0,1,.69.13,1.6,1.6,0,0,1,.54.38,1.85,1.85,0,0,1,.36.57,1.82,1.82,0,0,1,.13.7Z"/><path class="cls-2" d="M17.2,4.16a.63.63,0,0,0-.2-.47.69.69,0,0,0-.43-.16.55.55,0,0,0-.44.19.62.62,0,0,0-.16.43.68.68,0,0,0,.09.33.81.81,0,0,0,.43.29l.72.29a1.7,1.7,0,0,1,.94.72,2,2,0,0,1,.26,1,1.85,1.85,0,0,1-.52,1.3,1.61,1.61,0,0,1-.57.39,1.81,1.81,0,0,1-.74.15,1.76,1.76,0,0,1-1.24-.47,1.61,1.61,0,0,1-.41-.57,2,2,0,0,1-.17-.8h1.15a1.12,1.12,0,0,0,.18.47.53.53,0,0,0,.48.22.72.72,0,0,0,.48-.18.59.59,0,0,0,.21-.48.69.69,0,0,0-.14-.43,1,1,0,0,0-.48-.32l-.58-.21a2.06,2.06,0,0,1-.91-.64,1.66,1.66,0,0,1-.33-1A1.89,1.89,0,0,1,15,3.44a1.78,1.78,0,0,1,.4-.57,1.58,1.58,0,0,1,.56-.36,1.82,1.82,0,0,1,.7-.13,1.93,1.93,0,0,1,.69.13,1.75,1.75,0,0,1,.55.38,1.85,1.85,0,0,1,.36.57,2,2,0,0,1,.13.7Z"/><path class="cls-2" d="M19.2,8.54V0h1.22V3h0a1.53,1.53,0,0,1,.48-.47,1.39,1.39,0,0,1,.65-.16,1.26,1.26,0,0,1,.69.16,1.35,1.35,0,0,1,.4.39,1.18,1.18,0,0,1,.15.51,7.72,7.72,0,0,1,0,1V6.73a5.56,5.56,0,0,1-.05.8,1.56,1.56,0,0,1-.15.5,1.12,1.12,0,0,1-1.07.58,1.15,1.15,0,0,1-.7-.18A3.79,3.79,0,0,1,20.42,8v.55Zm2.44-4.21a1,1,0,0,0-.13-.51A.5.5,0,0,0,21,3.61a.57.57,0,0,0-.44.18.66.66,0,0,0-.18.48V6.63a.83.83,0,0,0,.17.54.52.52,0,0,0,.45.21.49.49,0,0,0,.45-.22,1.11,1.11,0,0,0,.15-.6Z"/><path class="cls-2" d="M23.76,4.49a4.83,4.83,0,0,1,0-.68A1.55,1.55,0,0,1,24,3.26a1.59,1.59,0,0,1,.62-.64,1.84,1.84,0,0,1,1-.24,1.87,1.87,0,0,1,1,.24,1.59,1.59,0,0,1,.62.64,1.55,1.55,0,0,1,.18.55,4.83,4.83,0,0,1,.05.68v2a4.72,4.72,0,0,1-.05.68,1.55,1.55,0,0,1-.18.55,1.59,1.59,0,0,1-.62.64,1.87,1.87,0,0,1-1,.24,1.84,1.84,0,0,1-1-.24A1.59,1.59,0,0,1,24,7.73a1.55,1.55,0,0,1-.18-.55,4.72,4.72,0,0,1,0-.68ZM25,6.69a.72.72,0,0,0,.17.52.53.53,0,0,0,.43.17A.55.55,0,0,0,26,7.21a.72.72,0,0,0,.16-.52V4.3A.74.74,0,0,0,26,3.78a.55.55,0,0,0-.44-.17.53.53,0,0,0-.43.17A.74.74,0,0,0,25,4.3Z"/><path class="cls-2" d="M28.2,4.49a4.83,4.83,0,0,1,.05-.68,1.55,1.55,0,0,1,.18-.55,1.59,1.59,0,0,1,.62-.64,1.84,1.84,0,0,1,1-.24,1.87,1.87,0,0,1,1,.24,1.59,1.59,0,0,1,.62.64,1.55,1.55,0,0,1,.18.55,4.83,4.83,0,0,1,.05.68v2a4.72,4.72,0,0,1-.05.68,1.55,1.55,0,0,1-.18.55,1.59,1.59,0,0,1-.62.64,1.87,1.87,0,0,1-1,.24,1.84,1.84,0,0,1-1-.24,1.59,1.59,0,0,1-.62-.64,1.55,1.55,0,0,1-.18-.55,4.72,4.72,0,0,1-.05-.68Zm1.22,2.2a.72.72,0,0,0,.17.52.53.53,0,0,0,.43.17.55.55,0,0,0,.44-.17.72.72,0,0,0,.16-.52V4.3a.74.74,0,0,0-.16-.52A.55.55,0,0,0,30,3.61a.53.53,0,0,0-.43.17.74.74,0,0,0-.17.52Z"/><path class="cls-2" d="M32.75,8.54V0H34V5.11h0l1.47-2.66H36.7L35.24,4.93,37,8.54H35.66l-1.1-2.63L34,6.83V8.54Z"/></g></svg>