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.