Issue 16: Gmail OAuth (Read-only)

[ShubhamKumarSahu-svg]

🧠 Overview

This issue introduces secure Gmail integration into SubSentry using Google OAuth with a strictly read-only scope (gmail.readonly).

The goal is to allow users to connect their Gmail account safely, without granting any permission to:

• Send emails
• Delete emails
• Modify emails

User trust is critical here — permissions must be minimal and transparent.

---

🎯 What You Will Build

You will implement:

• Google OAuth flow
• Gmail permission request (read-only only)
• Secure token handling

This enables SubSentry to access email metadata safely for automation in later issues.

---

🔧 Functional Requirements

• Implement OAuth using Google APIs

• Request ONLY this scope:

  https://www.googleapis.com/auth/gmail.readonly
  

• Store access & refresh tokens securely (environment variables / DB)

• Handle:

  • Permission denial
  • Token expiration
  • Invalid credentials

• Show meaningful error responses

---

✅ Key Expectations

• OAuth flow works end-to-end
• No broader permissions requested
• Tokens are never logged
• Clear success & failure handling
• Clean code structure

---

🚫 What NOT to do

• ❌ Request write / delete / send scopes
• ❌ Console.log tokens
• ❌ Hardcode client secrets
• ❌ Expose credentials in repo

---

🧪 Testing

• Successful Gmail connection
• Token refresh handling
• Proper error when permission denied

---

🏁 Outcome

After this issue:

• Users can safely connect Gmail
• System is ready for email fetching
• Security & privacy are preserved