1# config
 2
 3The `config` package handles all persistent application state: user configuration, email/contacts/drafts caching, folder caching, and email signatures. All data is stored as JSON files under `~/.config/matcha/`.
 4
 5## Architecture
 6
 7This package acts as the data layer for Matcha. It manages:
 8
 9- **Account configuration** with multi-account support (Gmail, iCloud, custom IMAP/SMTP)
10- **Secure credential storage** via the OS keyring (with automatic migration from plain-text passwords)
11- **Local caches** for emails, contacts, drafts, and folder listings to enable fast startup and offline browsing
12- **Email signatures** stored as plain text
13
14All cache files use JSON serialization with restrictive file permissions (`0600`/`0700`).
15
16## Files
17
18| File | Description |
19|------|-------------|
20| `config.go` | Core configuration types (`Account`, `Config`, `MailingList`) and functions for loading, saving, and managing accounts. Handles IMAP/SMTP server resolution per provider, OS keyring integration, and legacy config migration. |
21| `cache.go` | Email, contacts, and drafts caching. Provides CRUD operations for `EmailCache`, `ContactsCache` (with search and frequency-based ranking), and `DraftsCache` (with save/delete/get operations). |
22| `folder_cache.go` | Caches IMAP folder listings per account and per-folder email metadata. Stores folder names to avoid repeated IMAP `LIST` commands, and caches email headers per folder for fast navigation. |
23| `signature.go` | Loads and saves the user's email signature from `~/.config/matcha/signature.txt`. |
24| `oauth.go` | OAuth2 integration — token retrieval, authorization flow launcher, and embedded Python helper extraction. |
25| `oauth_script.py` | Embedded Gmail OAuth2 helper script (browser-based auth, token refresh, secure storage). |
26| `config_test.go` | Unit tests for configuration logic. |
27
28## OAuth2 / XOAUTH2
29
30Accounts with `auth_method: "oauth2"` use Gmail's XOAUTH2 mechanism instead of passwords. The flow works across three layers:
31
321. **`config/oauth.go`** — Go-side orchestration. Extracts the embedded Python helper to `~/.config/matcha/oauth/`, invokes it to run the browser-based authorization flow (`RunOAuth2Flow`) or to retrieve a fresh access token (`GetOAuth2Token`). The `IsOAuth2()` method on `Account` checks the auth method.
33
342. **`config/oauth_script.py`** — Embedded Python script that handles the full OAuth2 lifecycle:
35   - `auth` — Opens a browser for Google authorization, captures the callback on `localhost:8189`, exchanges the code for tokens, and saves them to `~/.config/matcha/oauth_tokens/`.
36   - `token` — Returns a fresh access token, automatically refreshing if expired (with a 5-minute buffer).
37   - `revoke` — Revokes tokens with Google and deletes local storage.
38   - Client credentials are stored in `~/.config/matcha/oauth_client.json`.
39
403. **`fetcher/xoauth2.go`** — Implements the XOAUTH2 SASL mechanism (`sasl.Client` interface) for IMAP/SMTP authentication. Formats the initial response as `user=<email>\x01auth=Bearer <token>\x01\x01` per Google's XOAUTH2 protocol spec.