create-neomutt-gmail 0.1.4 → 0.1.5

package/README.md

@@ -113,39 +113,82 @@ The wizard will:
 
 ## After Installation
 
+### Understanding the Authentication Flow
+
+This setup uses **two different security mechanisms**:
+
+| Component | Purpose | Where to get it |
+|-----------|---------|----------------|
+| **GPG Key** | Encrypts OAuth token on your disk | Create with `gpg --full-generate-key` |
+| **OAuth2 Credentials** | Authenticates with Gmail | Google Cloud Console |
+
+**Common mistake**: These are NOT the same thing. You need both.
+
+---
+
 ### Step 1: Google Cloud Console
 
 1. Visit https://console.cloud.google.com/
-2. Create a new project
-3. Enable Gmail API
-4. Configure OAuth consent screen (External)
-5. Add scope: `https://mail.google.com/`
-6. Add your email as test user
-7. Create OAuth client ID (Desktop application)
-8. Note Client ID and Client Secret
+2. Create a new project (e.g., "neomutt-gmail")
+3. Enable Gmail API:
+   - Go to "APIs & Services" → "Enable APIs and Services"
+   - Search for "Gmail API" and enable it
+4. Configure OAuth consent screen:
+   - User Type: **External** (for personal Gmail)
+   - App name: Any name (e.g., "Mutt Email Client")
+   - Add scope: `https://mail.google.com/`
+   - Add your email as test user
+5. Create OAuth client ID:
+   - Go to "Credentials" → "Create Credentials" → "OAuth client ID"
+   - Application type: **Desktop app**
+   - Name: Any name (e.g., "Mutt")
+6. **Save these credentials** (you'll need them in Step 2):
+   - Client ID (looks like: `123456789-abc.apps.googleusercontent.com`)
+   - Client Secret (looks like: `GOCSPX-abc123xyz`)
+
+---
 
 ### Step 2: Obtain OAuth Token
 
-Run the command shown by the wizard (it will look like this):
+Run this command (the wizard shows you the exact command):
 
 ```bash
 python3 ~/.config/mutt/mutt_oauth2.py \
   --authorize \
   --authflow localhostauthcode \
-  --encryption-pipe 'gpg --encrypt --recipient your@email.com' \
+  --encryption-pipe 'gpg --encrypt --recipient YOUR_EMAIL@gmail.com' \
   --client-id YOUR_CLIENT_ID.apps.googleusercontent.com \
   --client-secret YOUR_CLIENT_SECRET \
   --provider google \
-  --email your@email.com \
+  --email YOUR_EMAIL@gmail.com \
   ~/.local/etc/oauth-tokens/gmail.tokens
 ```
 
+**What each parameter means**:
+
+| Parameter | Example | Where from |
+|-----------|---------|-----------|
+| `--recipient` | `your@gmail.com` | Your GPG key (created with `gpg --full-generate-key`) |
+| `--client-id` | `123...apps.googleusercontent.com` | Google Cloud Console (Step 1) |
+| `--client-secret` | `GOCSPX-...` | Google Cloud Console (Step 1) |
+| `--email` | `your@gmail.com` | Your Gmail address |
+
+**What happens**:
+1. Browser opens for Google authentication
+2. You authorize the app
+3. Token is downloaded and encrypted with your GPG key
+4. You'll be prompted for your GPG passphrase
+
+---
+
 ### Step 3: Launch Neomutt
 
 ```bash
 neomutt
 ```
 
+You'll be prompted for your GPG passphrase when Neomutt reads the encrypted token.
+
 ## Keyboard Shortcuts
 
 Once Neomutt is running:
@@ -206,6 +249,8 @@ Create a GPG key:
 gpg --full-generate-key
 ```
 
+Remember: This GPG key is for **encrypting the OAuth token on your disk**, not for Google authentication.
+
 ### "Failed to download mutt_oauth2.py"
 
 Download manually:
@@ -217,7 +262,42 @@ chmod +x ~/.config/mutt/mutt_oauth2.py
 
 ### OAuth Token Issues
 
-See the [detailed troubleshooting guide](https://github.com/a-lost-social-misfit/terminal-blog) for OAuth-specific issues.
+**"Invalid credentials"**: Check that your Client ID and Secret are correct.
+
+**"Error decrypting token"**: Your GPG key might not be set up correctly. Run:
+```bash
+gpg --list-secret-keys
+```
+
+See the [detailed troubleshooting guide](https://github.com/a-lost-social-misfit/terminal-blog) for more help.
+
+## Common Misconceptions
+
+### GPG vs OAuth2
+
+**These are two completely different things:**
+
+- **GPG**: Local encryption tool
+  - Purpose: Encrypt the OAuth token file on your disk
+  - Where: Your computer (`gpg --full-generate-key`)
+  - When: Once, during initial setup
+  
+- **OAuth2**: Google's authentication protocol
+  - Purpose: Prove your identity to Gmail
+  - Where: Google Cloud Console
+  - When: You need Client ID and Secret from Google
+
+**You need BOTH**:
+1. Create a GPG key (once)
+2. Get OAuth credentials from Google (once)
+3. Run `mutt_oauth2.py` (uses both to create encrypted token)
+
+### Why use GPG encryption?
+
+The OAuth token allows full access to your Gmail. GPG encryption ensures:
+- Token is encrypted on disk
+- Only you (with GPG passphrase) can decrypt it
+- Safer than storing plain text
 
 ## Powered By
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-neomutt-gmail",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Interactive setup wizard for Neomutt + Gmail + OAuth2.0",
   "main": "src/index.js",
   "bin": {