emcli/specifications/PHASE3-STATUS.md

emcli — Phase 3 Status Report

Date: 2026-06-22 Branch: main Phase 3 (as specified): OAuth2 — Gmail loopback consent + token refresh (SPEC §10).

Outcome: OAuth2 deferred; Gmail handled via app password on the existing auth path

After evaluating the OAuth2 design against the actual use case (a personal, self-built CLI for one Gmail account), we chose not to build the OAuth2 machinery in this phase. Gmail is instead accessed with a Google App Password over emcli's existing password auth (Phases 1–2) — and it was validated live, end-to-end. No new code was required.

Why OAuth2 was deferred (not just "skipped")

A self-built tool cannot replicate the "Log in with Google" experience of verified clients (Mailspring, Thunderbird, Aerion) without owning a verified, published OAuth app. For a personal embed the options are all poor:

• Unverified app in "Testing" publishing status → Google expires refresh tokens every 7 days, forcing weekly re-consent. Unusable for an unattended tool.
• Unverified app in "Production" status → refresh tokens are long-lived, but every login shows the "Google hasn't verified this app" warning, and https://mail.google.com/ is a restricted scope (full verification needs a paid security assessment). Workable, but heavy setup for one user.
• App Password (chosen) → requires only that 2-Step Verification is enabled. Yields a permanent 16-character credential usable with standard IMAP/SMTP password auth. No consent screen, no 7-day expiry, no client ID/secret, no Google Cloud project. Revoked only on manual revoke, main-password change, or disabling 2FA.

For a single-user personal tool, the App Password is strictly simpler and more robust, and it reuses the IMAP/SMTP password path already shipped and tested in Phases 1–2.

OAuth2 remains a clean future addition (SPEC §10, schema columns already present) if emcli ever needs multi-user/provider support or a verified app. The mechanism would be: x/oauth2 loopback consent + an XOAUTH2 sasl.Client (go-sasl ships OAUTHBEARER but not XOAUTH2) wired into the existing mail.Dial/SendSMTP auth branch. Nothing in Phases 1–2 blocks it.

Live validation (real Gmail account, app password)

A real personal Gmail account over verified TLS (imap.gmail.com:993, smtp.gmail.com:465), authenticating with a Gmail app password via the existing password auth:

• list: returned real INBOX headers (newest-first), has_attachments correct.
• get: returned the full decoded plain-text body of a Gmail message.
• search: --from/--subject-contains narrowed correctly server-side.
• send: delivered a message to me@stevecliff.com — {"sent":true}, exit 0.
• Round-trip: a self-addressed send arrived and was found via IMAP search on the first poll — full SMTP-out → IMAP-in proof.
• All over emcli's existing code; the app password is sealed at rest in the encrypted DB.

Gmail setup (app password)

1. Enable 2-Step Verification on the Google account (required — the app-passwords page is hidden otherwise).
2. Create a 16-character app password at https://myaccount.google.com/apppasswords (name it e.g. "emcli").
3. Enable IMAP in Gmail: Settings → Forwarding and POP/IMAP → Enable IMAP.
4. Add the account (app password is entered as the password; spaces are stripped):

   emcli account add --name gmail --mode RW \
     --imap-host imap.gmail.com --imap-port 993 --imap-security tls \
     --smtp-host smtp.gmail.com --smtp-port 465 --smtp-security tls \
     --username you@gmail.com --password '<16-char-app-password>'
   

App passwords are revoked by a main-password change or disabling 2FA; regenerate and re-run account add if that happens.

Code changes

None. The speculative OAuth store fields/tests started early in the session were reverted; the working tree is byte-for-byte the Phase 2 code plus this document. Full suite remains green.

Known limitations / deferred

• OAuth2 (SPEC §10) — deferred as above; revisit for multi-user/provider or a verified app.
• Phase 4 — admin TUI + doctor — unchanged; next up.
• Carry-over Minor items from Phase 1 remain open.