feature: users can be enrolled for TOTP one-time passwords.

ADR.md

@@ -247,3 +247,27 @@ serves them under `/groups`. Group names follow the rules of user names.
 Consequences: A group always satisfies the schema without a placeholder member, and an empty
 group cannot exist. Removing a user or a member can need another step first. A later use of
 groups, such as allowing OpenVPN only to some, can read them as they are.
+
+## ADR-12: TOTP secrets are kept with the OATH-LDAP schema of slapd's otp module
+
+Status: Accepted
+
+Context: Users are to be enrolled for TOTP one-time passwords, with nothing checking the codes
+yet. Ubuntu's slapd ships the `otp` module, which holds the OATH-LDAP schema and an overlay that
+checks a code appended to the password at bind time. Ubuntu packages `python3-pyotp`. An
+authenticator app is enrolled from a QR code of an `otpauth://` URI.
+
+Decision: The `otp` module is loaded for its schema; its overlay is not configured. The TOTP
+token is the user entry itself: enrolment adds `oathTOTPUser` and `oathTOTPToken` to it, with
+`oathTOTPToken` naming the entry, the secret in `oathSecret` and `oathTOTPParams` naming one
+shared parameter entry, `cn=totp,ou=policies`, with the parameters authenticator apps assume
+(6 digits, HMAC-SHA1, 30 seconds). An ACL lets the user manager account set `oathSecret` and
+no one read it. Enrolment is confirmed: `otp_new` makes a secret with `pyotp` and returns it
+with its URI, storing nothing, and `otp_enrol` stores the secret it is given back only when a
+code of it verifies, so a secret is never stored that the user's app does not produce. The
+router answers the URI; the client renders the QR code.
+
+Consequences: Removing a user removes its token. Configuring the overlay later makes slapd
+check the stored tokens without moving data. The secret passes through the client between
+`otp_new` and `otp_enrol`, so the router keeps no pending state; enrolling again replaces the
+secret only once a code of the new one verifies.