Expand OAuth2 Support for CLI and Long-Running Integrations

[shalev007]

Problem:
RestBook currently supports several OAuth2 grant types (client_credentials, password, refresh_token), but lacks full support for real-world OAuth2 scenarios required by many APIs (e.g., Google, GitHub, Dropbox). In particular, authorization_code is only partially implemented, and other flows like PKCE and Device Code are missing entirely.

---

✅ Currently Supported

Grant Type	Description	Status
client_credentials	Server-to-server auth	✅ Implemented
password	Username/password (legacy)	✅ Implemented
refresh_token	Token refresh logic	✅ Implemented
authorization_code	Requires manual code injection	⚠️ Partial

---

🛠 Missing Features & What to Add

🟥 1. Authorization Code Flow (Complete Flow)

• Generate authorize_url
• Open browser or display URL for user to visit
• Prompt user to paste back code
• (Optional) Local server to catch redirect and extract code

🟥 2. PKCE Support

• Generate code_verifier and code_challenge
• Append them to the auth URL and token exchange

Required by: Google, Dropbox, and other APIs when client_secret isn’t used

🟧 3. Device Code Flow

• Request device_code from API
• Show user the code and URL to complete login
• Poll for access token

Useful for: CLI/headless use cases

🟨 4. Token Expiration Tracking

• Parse expires_in from token response
• Calculate and store expiration time
• Auto-refresh when token is close to expiry

🟨 5. Token Caching

• Save access_token, refresh_token, and expiry to disk
• Load cached token on future runs (if still valid)
• Optional cache file path: .restbook/tokens/{session}.json

---

💡 Why This Matters

• Enables support for APIs like GitHub, Google, Notion, and Microsoft
• Makes RestBook fully usable for interactive, cron, and CI use cases
• Eliminates manual token handling for end users

---

📎 Related Ideas

• Possibly implement restbook auth command for interactive flows
• Store session data in .restbook/ directory for better visibility