halkyon/docs/adr/0010-email-sign-in.md

ADR 0010: Signing in with an email address, keeping only a keyed hash of it

• Status: accepted
• Date: 2026-10-15

Context

People keep an anonymous account by linking an identity, which makes them identified: they can sign in on another device, publish, report and suggest. Until now the only identity was GitHub, which many learners don't have. The developer asked for email sign-up first among the features after the hackathon (11 Oct).

GitHub sign-in keeps only the numeric GitHub ID (decided 2026-09-30): the instance holds no personal data of anybody beyond what they write. Serverpod's email sign-in (checked with v4.0.4) doesn't fit that. It keeps the address in plain text in three tables (the account, the pending registration, and a user profile it creates), works with passwords (Argon2id) and resets by mailed codes, and finishing a registration always creates a new person, so an anonymous account can't be upgraded in place with it. Its building blocks are public, though: code challenges kept as Argon2id hashes, with expiry, a limit on tries and completion tokens (SecretChallengeUtil), and a rate limiter (DatabaseRateLimiter).

Decision

1. The instance keeps a keyed hash of the address, never the address. An address is trimmed and put in lower case; the instance keeps HMAC-SHA256 of it, keyed with its own emailSignInPepper (in passwords.yaml, SERVERPOD_PASSWORD_emailSignInPepper in production), in hex (addressHash in lib/src/auth/email.dart). email_identity holds the person and the hash, one address per person and each address one person's. From what someone types, the instance can still find the person and tell whether an address is free; it mails only an address someone has just typed, to send a code; it can't write to anybody otherwise, nor show anybody their address. The device that signed in remembers the address, to show it (sign_in.json in the person's folder, which goes with the rest of their data).
2. A code by mail each time, no password. A code is eight characters of Crockford's base 32 (K7QX-M2PD, as the assistant's connect codes), valid 15 minutes and 3 tries, kept as Serverpod's SecretChallenge (Argon2id with the same pepper); a newer code for an address replaces the older one. No password is stored, reset or leaked.
3. The same answer for every address. Mailing a code answers alike whether anybody has the address. Only once the code proves the mailbox does the instance say whose it is.
4. As GitHub works. A code for an address nobody has makes it the signed-in person's, in one transaction: they become identified, on their sessions too, and lose their anonymous identity, keeping everything. A code for another person's address changes nothing and gives a switch token (Serverpod's completion token), which signs in as that person without a session (emailSignIn.signIn, as Serverpod issues no session for another person inside a signed-in call), once, within the 15 minutes; the device then deletes the anonymous account it leaves behind, as nobody could sign into it again. Someone identified is never switched, by GitHub either: the app tells them the address or GitHub account is another account's, as their own account would otherwise be left behind (and the app's switch deleted only what it left behind, whoever that was; now only an anonymous account).
5. Two ways in. A person may sign in with GitHub and with an address, one of each (account.signInWays); the Profile tab lists them and adds the one missing.
6. Limits. At most 3 codes an hour for one address (counted by its hash) and 10 from one network (IP address); the rate limiter's notes, which hold the IP address, go hourly with the anonymous sign-ups' (forgetOldSignUpAttempts), and codes past their time hourly too (forgetExpiredEmailCodes).
7. Mail. Codes go over SMTP, through whichever service the operator sets up in the passwords (emailSmtpHost, emailSmtpPort, emailSmtpUser, emailSmtpPassword, emailFrom; deploy/.env in production), with pub.dev's mailer (MIT), over TLS only (STARTTLS, or TLS directly on port 465). learn.halkyon.eu sends through Proton's SMTP submission (decided 2026-10-15, over Scaleway TEM): a token for an address on its own domain. The mail is plain text: the code first and in the subject, so it shows in the notification and the system can offer it, which instance it signs in to, its 15 minutes, and that it can be ignored; no links, no tracking, no HTML. A mail that couldn't be sent is a refusal of its own (mailFailed), keeping nothing of the request; the log names the error's type only, as the service's answer may name the address. Without a service, codes go to the server's log in development (LogCodeMailer), and elsewhere the instance offers no email sign-in (instance.info().emailSignIn).
8. The pepper never changes once anybody signs in with an address: every hash would be lost, and with it those people's way in. Rotating it would need a list of earlier peppers tried in turn, which isn't built.

Consequences

• The instance can send no notices: no "your sign-in changed", no newsletter. A breach would be communicated publicly (GDPR Article 34(3)(c)), as the instance holds no way to reach people.
• Whoever has both the database and the pepper can check whether a guessed address signs in here, but can't list the addresses. Without the pepper, the hashes tell nothing.
• Someone who loses their mailbox loses that way in, as someone who loses their GitHub account loses that one; a second way in is the remedy.
• Every sign-in on a new device needs a mail. Sessions last until 90 days unused, so that is rare.
• Deleting a person deletes their hash (deletePerson); a restore from backup brings it back with the rest.