Update documentation

doc/src/notes.md

@@ -1,4 +1,42 @@
 # Notes
 
+An IMAP trace extracted from Aerogramme:
 
-*No note currently*
+```
+S: * OK Hello
+C: A1 LOGIN alan p455w0rd
+S: A1 OK Completed
+C: A2 SELECT INBOX
+S: * 0 EXISTS
+S: * 0 RECENT
+S: * FLAGS (\Seen \Answered \Flagged \Deleted \Draft)
+S: * OK [PERMANENTFLAGS (\Seen \Answered \Flagged \Deleted \Draft \*)] Flags permitted
+S: * OK [UIDVALIDITY 1] UIDs valid
+S: * OK [UIDNEXT 1] Predict next UID
+S: A2 OK [READ-WRITE] Select completed
+C: A3 NOOP
+S: A3 OK NOOP completed.
+        <---- e-mail arrives through LMTP server ---->
+C: A4 NOOP
+S: * 1 EXISTS
+S: A4 OK NOOP completed.
+C: A5 FETCH 1 FULL
+S: * 1 FETCH (UID 1 FLAGS () INTERNALDATE "06-Jul-2022 14:46:42 +0000" 
+      RFC822.SIZE 117 ENVELOPE (NIL "test" (("Alan Smith" NIL "alan" "smith.me")) 
+      NIL NIL (("Alan Smith" NIL "alan" "aerogramme.tld")) NIL NIL NIL NIL) 
+      BODY ("TEXT" "test" NIL "test" "test" "test" 1 1))
+S: A5 OK FETCH completed
+C: A6 FETCH 1 (RFC822)
+S: * 1 FETCH (UID 1 RFC822 {117}
+S: Subject: test
+S: From: Alan Smith <alan@smith.me>
+S: To: Alan Smith <alan@aerogramme.tld>
+S: 
+S: Hello, world!
+S: .
+S: )
+S: A6 OK FETCH completed
+C: A7 LOGOUT
+S: * BYE Logging out
+S: A7 OK Logout completed
+```

doc/src/setup.md

@@ -8,10 +8,14 @@ cargo run -- first-login \
   --k2v-endpoint http://127.0.0.1:3904 \
   --s3-endpoint http://127.0.0.1:3900 \
   --aws-access-key-id GK... \
-  --aws-secret-access-key c0ffee... --bucket mailrage-me \
+  --aws-secret-access-key c0ffee... \
+  --bucket mailrage-me \
   --user-secret s3cr3t
 ```
 
+*Note: user-secret is not the user's password. It is an additional secret used when deriving user's secret key from their password. The idea is that, even if user leaks their password, their encrypted data remain safe as long as this additional secret does not leak. You can generate it with openssl for example: `openssl rand -base64 30`. Read [Cryptography & key management](./crypt-key.md) for more details.*
+
+
 The program will interactively ask you some questions and finally generates for you a snippet of configuration:
 
 ```
@@ -39,12 +43,24 @@ s3_endpoint = "http://127.0.0.1:3900"
 k2v_endpoint = "http://127.0.0.1:3904"
 aws_region = "garage"
 
+[lmtp]
+bind_addr = "[::1]:12024"
+hostname = "aerogramme.tld"
+
+[imap]
+bind_addr = "[::1]:1993"
+
 [login_static]
 default_bucket = "mailrage"
+
 [login_static.users.me]
 bucket = "mailrage-me"
 user_secret = "s3cr3t"
-alternate_user_secrets = []
+email_addresses = [
+  "me@aerogramme.tld"
+]
+
+# copy pasted values from first-login
 password = "$argon2id$v=19$m=4096,t=3,p=1$..."
 aws_access_key_id = "GK..."
 aws_secret_access_key = "c0ffee..."
@@ -58,8 +74,8 @@ cargo run -- show-keys \
   --k2v-endpoint http://127.0.0.1:3904 \
   --s3-endpoint http://127.0.0.1:3900 \
   --aws-access-key-id GK... \
-   --aws-secret-access-key c0ffee... \
-  --bucket mailrage-me 
+  --aws-secret-access-key c0ffee... \
+  --bucket mailrage-me \
   --user-secret s3cr3t
 ```
 

doc/src/validate.md

@@ -6,43 +6,35 @@ Start a server as follow:
 cargo run -- server
 ```
 
-Now you can use netcat to connect on the LMTP and IMAP endpoint to check that Aerogramme behaves as expected. As an example, here is an IMAP trace extracted from Aerogramme:
+Inject emails:
 
+```bash
+./test/inject_emails.sh '<me@aerogramme.tld>' dxflrs
 ```
-S: * OK Hello
-C: A1 LOGIN lx plop
-S: A1 OK Completed
-C: A2 SELECT INBOX
-S: * 0 EXISTS
-S: * 0 RECENT
-S: * FLAGS (\Seen \Answered \Flagged \Deleted \Draft)
-S: * OK [PERMANENTFLAGS (\Seen \Answered \Flagged \Deleted \Draft \*)] Flags permitted
-S: * OK [UIDVALIDITY 1] UIDs valid
-S: * OK [UIDNEXT 1] Predict next UID
-S: A2 OK [READ-WRITE] Select completed
-C: A3 NOOP
-S: A3 OK NOOP completed.
-        <---- e-mail arrives through LMTP server ---->
-C: A4 NOOP
-S: * 1 EXISTS
-S: A4 OK NOOP completed.
-C: A5 FETCH 1 FULL
-S: * 1 FETCH (UID 1 FLAGS () INTERNALDATE "06-Jul-2022 14:46:42 +0000" 
-      RFC822.SIZE 117 ENVELOPE (NIL "test" (("Alan Smith" NIL "alan" "smith.me")) 
-      NIL NIL (("Alan Smith" NIL "alan" "aerogramme.tld")) NIL NIL NIL NIL) 
-      BODY ("TEXT" "test" NIL "test" "test" "test" 1 1))
-S: A5 OK FETCH completed
-C: A6 FETCH 1 (RFC822)
-S: * 1 FETCH (UID 1 RFC822 {117}
-S: Subject: test
-S: From: Alan Smith <alan@smith.me>
-S: To: Alan Smith <alan@aerogramme.tld>
-S: 
-S: Hello, world!
-S: .
-S: )
-S: A6 OK FETCH completed
-C: A7 LOGOUT
-S: * BYE Logging out
-S: A7 OK Logout completed
+
+Now you can connect your mailbox with `mutt`.
+Start by creating a config file, for example we used the following `~/.muttrc` file:
+
+```ini
+set imap_user = quentin
+set imap_pass = p455w0rd
+set folder = imap://localhost:1993
+set spoolfile = +INBOX
+set ssl_starttls = no
+set ssl_force_tls = no
+mailboxes = +INBOX
+bind index G imap-fetch-mail
 ```
+
+And then simply launch `mutt`.
+The first time nothing will happen as Aerogramme must
+process your incoming emails. Just ask `mutt` to refresh its
+view by pressing `G` (for *Get*).
+
+Now, you should see some emails:
+
+![Screenshot of mutt mailbox](./mutt_mb.png)
+
+And you can read them:
+
+![Screenshot of mutt mail view](./mutt_mail.png)

tests/inject_emails.sh

@@ -1,12 +1,15 @@
 #!/bin/sh
 
-cd $(dirname $0)
+SCRIPT=$0
+USER=$1
+SUBFOLDER=$2
+cd $(dirname $SCRIPT)
 
 function mail_lmtp_session (
 	echo -e "LHLO localhost\r"
-	for mail in $(find emails -name '*.eml'); do
+	for mail in $(find emails/$SUBFOLDER -name '*.eml' ); do
 		echo -e "MAIL FROM: <alex@adnab.me>\r"
-		echo -e "RCPT TO: <lx@staging.deuxfleurs.org>\r"
+		echo -e "RCPT TO: $USER\r"
 		echo -e "DATA\r"
 		cat $mail
 		echo -e "\r"