Add step-by-step Microsoft app registration guide for Mail

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

README.md

@@ -78,7 +78,7 @@ e.g. hub.necloud.us. Settings: `SEAFILE_URL`, `ONLYOFFICE_URL` env vars in docke
 - **Podcast** and **Podcast Admin**: launchers that open `PODCAST_URL` (a home-network address) and `VERSE_URL` in their own tabs.
 - **Office**: embeds onlyoffice.necloud.us in a frame, with an "open in new tab" fallback if it blocks framing.
 - **Mail**: your **Outlook.com** (personal) mailbox inside the app: folders with unread counts, message list with search, reader, compose with attachments (up to about 3 MB), reply, reply all, forward, archive, delete, flag, mark unread, an unread badge on the Mail tab and a Home card. It uses Microsoft Graph, because Outlook.com no longer allows IMAP passwords. Each person connects their own mailbox (Mail tab -> Connect Outlook.com, sign-in is on Microsoft's own page); the hub keeps only the sign-in token, encrypted, in that person's folder, and everything is private to them. Message text is shown in a sandboxed frame with no scripts, and pictures from the internet stay hidden until you press Show pictures. Not included: drafts autosave, contacts, several mailboxes per person, Microsoft 365 work accounts, Gmail/iCloud (those can be added the same way later).
-  **One-time setup** (needs a free Microsoft account; takes five minutes): go to entra.microsoft.com -> App registrations -> New registration. Name it NE Hub; supported account types **Personal Microsoft accounts only**; Redirect URI: platform **Web**, value `<your hub address>/api/mail/callback` (for example `https://hub.necloud.us/api/mail/callback`; it must match `PUBLIC_URL` exactly). Then API permissions -> Add -> Microsoft Graph -> Delegated: `Mail.ReadWrite`, `Mail.Send`, `User.Read`, `offline_access`. Copy the **Application (client) ID** into `MS_CLIENT_ID`. If you registered it as a Web app, also make a client secret (Certificates & secrets) and put its value in `MS_CLIENT_SECRET`; if you used platform "Mobile and desktop applications" instead, no secret is needed. Leave `MS_CLIENT_ID` empty to switch Mail off. (The old bundled Cypht webmail and its `nehub-cypht` volume are gone; you can delete that volume.) Connecting from the installed iPhone/iPad app may open Microsoft's page in Safari; if the app does not notice, reopen it.
+  **One-time setup** (step by step, with troubleshooting, in [docs/mail-setup.md](docs/mail-setup.md); needs a free Microsoft account and takes five minutes): go to entra.microsoft.com -> App registrations -> New registration. Name it NE Hub; supported account types **Personal Microsoft accounts only**; Redirect URI: platform **Web**, value `<your hub address>/api/mail/callback` (for example `https://hub.necloud.us/api/mail/callback`; it must match `PUBLIC_URL` exactly). Then API permissions -> Add -> Microsoft Graph -> Delegated: `Mail.ReadWrite`, `Mail.Send`, `User.Read`, `offline_access`. Copy the **Application (client) ID** into `MS_CLIENT_ID`. If you registered it as a Web app, also make a client secret (Certificates & secrets) and put its value in `MS_CLIENT_SECRET`; if you used platform "Mobile and desktop applications" instead, no secret is needed. Leave `MS_CLIENT_ID` empty to switch Mail off. (The old bundled Cypht webmail and its `nehub-cypht` volume are gone; you can delete that volume.) Connecting from the installed iPhone/iPad app may open Microsoft's page in Safari; if the app does not notice, reopen it.
 
 ## Install on iPhone / iPad (PWA)
 

docs/mail-setup.md

@@ -0,0 +1,74 @@
+# Setting up Outlook.com mail (Microsoft app registration)
+
+NE Hub reads and sends your Outlook.com (personal) mail through Microsoft Graph. Microsoft requires every app that does this to be registered once. It is free and takes about five minutes. The steps follow the Entra portal; Microsoft changes the layout now and then, so a label may differ slightly.
+
+## 1. Open the registration page
+
+1. Go to **entra.microsoft.com** and sign in with any Microsoft account. It does not have to be the mailbox you will read.
+2. If it says you need a directory or Azure subscription, accept the free "Default Directory" it offers. The free tier is enough and costs nothing.
+3. In the left menu open **Entra ID -> App registrations -> New registration**.
+
+## 2. Fill in the registration
+
+- **Name:** `NE Hub`.
+- **Supported account types:** choose **Personal Microsoft accounts only**. This matches the hub, which signs in through Microsoft's "consumers" endpoint.
+- **Redirect URI:** set the platform to **Web** and enter `https://hub.necloud.us/api/mail/callback`. Use your real hub address. It must match `PUBLIC_URL` in your `.env` exactly: same `https`, same host, no trailing slash.
+- Press **Register**.
+
+## 3. Copy the client ID
+
+On the app's **Overview** page, copy the **Application (client) ID** (a long GUID). It goes in `MS_CLIENT_ID`.
+
+## 4. Add the mail permissions
+
+1. Open **API permissions -> Add a permission -> Microsoft Graph -> Delegated permissions**.
+2. Tick these four and press **Add permissions**:
+   - `Mail.ReadWrite`
+   - `Mail.Send`
+   - `User.Read`
+   - `offline_access`
+3. You do not need "Grant admin consent". Personal accounts approve these themselves the first time they connect.
+
+## 5. Create a client secret
+
+1. Open **Certificates & secrets -> New client secret**.
+2. Give it any name and choose the longest expiry (24 months).
+3. Copy the **Value** column right away. Microsoft shows it only once. It goes in `MS_CLIENT_SECRET` (not the "Secret ID").
+4. Put a reminder in your calendar for about 23 months from now. When the secret expires, Connect fails until you make a new one and update `MS_CLIENT_SECRET`.
+
+(If you would rather not have a secret, register the redirect under the platform **Mobile and desktop applications** instead of **Web** and leave `MS_CLIENT_SECRET` empty. The hub signs in with PKCE either way.)
+
+## 6. Give the hub the values
+
+Add these to your `.env` (or your stack's environment settings):
+
+```
+MS_CLIENT_ID=<the Application (client) ID>
+MS_CLIENT_SECRET=<the secret Value>
+PUBLIC_URL=https://hub.necloud.us
+```
+
+Then redeploy the hub:
+
+```
+docker compose up -d
+```
+
+Leave `MS_CLIENT_ID` empty to switch Mail off.
+
+## 7. Connect
+
+1. Open the hub, go to **Mail**, and press **Connect Outlook.com**.
+2. Sign in with your Outlook.com account on Microsoft's page and approve the permissions.
+3. You land back on the Mail tab with your inbox showing.
+
+Each person who has the Mail tab connects their own mailbox. The hub keeps only the sign-in token, encrypted, in that person's own folder.
+
+## If something goes wrong
+
+- **"redirect URI doesn't match" (AADSTS50011):** the address in step 2 differs from what the hub sends. Compare `PUBLIC_URL` and the registered URI character by character.
+- **"invalid client secret" or `invalid_client`:** you pasted the Secret ID instead of the Value, or the secret has expired. Make a new one.
+- **"app not found in directory/consumers":** the account type was not set to personal accounts only. Check it under **Authentication -> Supported account types**.
+- **The Mail tab says "Mail is not set up on this server":** `MS_CLIENT_ID` is empty or the container was not restarted after you added it.
+- **Connect works, then later says Microsoft signed you out:** the sign-in token was revoked, for example after a password change. Press Connect again.
+- **Installed iPhone/iPad app:** Microsoft's page may open in Safari. Sign in there, then reopen the app.