Update documentation

6 files changed, 94 insertions, 45 deletions

diff --git a/doc/src/mutt_mail.png b/doc/src/mutt_mail.png
new file mode 100644
index 0000000..e8d04e4
--- /dev/null
+++ b/doc/src/mutt_mail.png
diff --git a/doc/src/mutt_mb.png b/doc/src/mutt_mb.png
new file mode 100644
index 0000000..d1bafaf
--- /dev/null
+++ b/doc/src/mutt_mb.png
diff --git a/doc/src/notes.md b/doc/src/notes.md
index 33c98a0..3a4c954 100644
--- a/doc/src/notes.md
+++ b/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
+```
diff --git a/doc/src/setup.md b/doc/src/setup.md
index 66a1b7e..f954ae3 100644
--- a/doc/src/setup.md
+++ b/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
 ```
 
diff --git a/doc/src/validate.md b/doc/src/validate.md
index 9f4f6ec..57903f6 100644
--- a/doc/src/validate.md
+++ b/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)
diff --git a/tests/inject_emails.sh b/tests/inject_emails.sh
index 1b1f5c7..a021170 100755
--- a/tests/inject_emails.sh
+++ b/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"