# 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.