PRJ-email-config: Terminal Email with OAuth2 & age Encryption

1. Project Summary

Field Value

PRJ ID

PRJ-2025-TOOL-003

Date Created

~2025

Owner

Evan Rosado

Priority

P3 (Infrastructure utility)

Category

Personal Infrastructure / Email Client Configuration

Status

Stable (minimal maintenance)

Commits

1

Repository

github.com/EvanusModestus/email-config (private)

Local Path

~/atelier/_projects/personal/email-config

2. Purpose

email-config provides a secure terminal email setup with OAuth2 authentication for Outlook and Gmail. It uses aerc as the primary email client with age-encrypted OAuth2 tokens, eliminating the need for plaintext credentials on disk.

The configuration is designed for the privacy-conscious terminal workflow — all email operations happen in the terminal with tokens encrypted at rest via age and decrypted on-demand.

3. Scope

3.1. Components

Component Purpose

aerc/

Active email client configuration (accounts, main config, keybindings)

scripts/oauth2-token.sh

Token retrieval and refresh (decrypt age file, check expiry, refresh via Microsoft API)

scripts/setup-oauth2.sh

Initial OAuth2 setup wizard (Azure AD app registration flow)

accounts/

Legacy NeoMutt account configs (outlook.muttrc, gmail.muttrc)

neomuttrc, mbsyncrc, msmtprc

Legacy email stack (NeoMutt + mbsync + msmtp) — kept for reference

3.2. Security Model

  • Public (git-tracked): aerc config, OAuth2 scripts, legacy configs

  • age-encrypted: OAuth2 tokens at ~/.secrets/email/*.age

  • Local only: Mail cache (~/Mail/), aerc temp files

3.3. Token Lifecycle

  1. Initial setup runs Azure AD OAuth2 flow in browser

  2. Tokens encrypted with age and saved to ~/.secrets/email/

  3. aerc startup calls oauth2-token.sh which decrypts, checks expiry, refreshes if needed

  4. Re-encrypted tokens saved back to age file

4. Status

Aspect Status

Active Use

Stable — operational email client config

Commits

1 (single initial commit with complete setup)

Maintenance

Minimal — only changes for new accounts or OAuth2 updates

Dependencies

aerc, jq, curl, age

5. Related

6. Metadata

Field Value

PRJ ID

PRJ-2025-TOOL-003

Author

Evan Rosado

Date Created

~2025

Last Updated

2026-03-30

Status

Stable

Next Review

N/A