mailbox-reader

A minimal Node.js app that reads your own Microsoft 365 mailbox via Microsoft Graph.

It uses delegated Mail.Read with the authorization code + PKCE flow as a public client (no client secret). With delegated permissions the token is bound to the signed-in user, so the app can only ever read the mailbox of whoever logged in — there is no code path to another user's inbox.

What's in here

| File | Purpose | |------|---------| | src/auth.js | MSAL sign-in (PKCE), silent token renewal, persistent cache | | src/index.js | Reads /me/messages and prints the latest N | | .env.example | Config template — copy to .env |

1. Register the app in Entra ID (one-time)

1. Go to Entra admin center → Identity → Applications → App registrations → New registration.
2. Name: mailbox-reader (anything).
3. Supported account types: Accounts in this organizational directory only (single tenant) is the safest default.
4. Redirect URI: choose platform Mobile and desktop applications, value http://localhost.
   • You can also add it later under Authentication → Add a platform → Mobile and desktop applications → check http://localhost.
5. Under Authentication, ensure Allow public client flows is set to Yes (this is a public client — no secret).
6. API permissions → Add a permission → Microsoft Graph → Delegated permissions → add Mail.Read (or Mail.ReadBasic for metadata only).
   • offline_access is requested automatically for refresh tokens.
   • If your tenant requires admin consent, click Grant admin consent (otherwise you'll just consent yourself on first sign-in).
7. Copy the Application (client) ID and Directory (tenant) ID from the app's Overview page.

2. Configure

cd mailbox-reader
cp .env.example .env
# edit .env — paste your CLIENT_ID and TENANT_ID
npm install

3. Run

npm start          # sign in (first run) and list your latest messages
npm run login      # just sign in / confirm whose mailbox is connected
npm run logout     # clear the local token cache

First run opens a browser for Microsoft sign-in. After that, a refresh token in .token-cache.json renews access silently — no repeated prompts.

Security notes

• No client secret. Public client + PKCE keeps credentials with Microsoft's login.
• Self-scoped by design. Delegated Mail.Read can only read the signed-in user's mailbox.
• Mail.ReadBasic (set SCOPES=Mail.ReadBasic in .env) drops message body and attachments — a tighter blast radius if a token ever leaks.
• The real secret is .token-cache.json — it holds the refresh token. It's git-ignored and written with 0600 perms. Delete it (npm run logout) to revoke this machine's access; revoke fully under My Account → Security info / app access.
• Never commit .env or .token-cache.json.