feat: Implement GitHub bot for reduced OAuth scope and fix chatbot issue filing

[sethwebster]

Summary

Implements a GitHub bot account to handle write operations (filing issues, creating PRs) on behalf of users, reducing OAuth scope requirements from public_repo to just read:user user:email. This makes users much more comfortable granting permissions since they're no longer giving write access to ALL their public repositories.

Also fixes three critical chatbot bugs where it was incorrectly handling issue filing.

Changes

OAuth Scope Reduction

• ✅ Reduced user OAuth scope from public_repo to read:user user:email (src/lib/auth.ts:16)
• ✅ Users no longer grant write access to all public repositories
• ✅ Much less intimidating OAuth permission prompt

GitHub Bot Service

New file: src/lib/github-bot.ts

• fileIssue() - File issues on behalf of users with clear attribution
• addComment() - Add comments to issues with user attribution
• isBotConfigured() - Check if bot token is configured
• getBotInfo() - Get bot account details
• All actions include attribution: > **Filed by @username via React Foundation Store**

API Endpoint

New file: src/app/api/bot/file-issue/route.ts

• POST /api/bot/file-issue for filing issues via bot
• Requires user authentication (NextAuth session)
• Comprehensive validation and error handling
• Proper GitHub API error handling (404, 403, 410)

React Hook

New file: src/lib/hooks/use-github-bot.ts

• useGitHubBot() hook for easy frontend integration
• Built-in loading states and error handling
• Simple, clean API for components

Chatbot Integration Fixes

Modified: src/app/api/chat/route.ts

Fixed three critical issues:

1. ❌ Was saying "user is not authenticated" when they WERE authenticated

   • ✅ Fixed: Corrected authentication status detection (line 672-676)

2. ❌ Was asking "Would you like me to create this issue under your GitHub account or as the bot?"

   • ✅ Fixed: Removed unnecessary prompt, always uses bot (line 50)

3. ❌ Was filing as user (@sethwebster) instead of bot

   • ✅ Fixed: Now always uses bot service with user attribution (line 449-480)

Environment & Testing

• Added GITHUB_BOT_TOKEN to .env.example with setup instructions
• Created test script (scripts/test-bot.ts) to verify bot configuration
• Added dotenv dependency for standalone test script

Documentation

New file: docs/development/github-bot-setup.md

• Complete setup guide (bot account creation, token generation)
• API usage examples (frontend, backend, direct POST)
• Security considerations (rate limiting, validation, monitoring)
• Troubleshooting guide
• Added to docs/README.md index

Benefits

✅ Users feel safe - Only minimal read permissions required
✅ Full functionality - Bot performs all write operations
✅ Clear attribution - Shows who filed each issue
✅ Centralized control - Rate limiting, validation, moderation
✅ Better UX - No scary OAuth prompts
✅ Fixed chatbot - Correctly files issues as bot with attribution

Testing

Bot account created and tested:

🤖 Testing GitHub Bot Configuration...
✅ Bot token is configured
✅ Successfully connected to GitHub!

Bot Account Details:
─────────────────────────────────────
Username:  react-foundation-bot
Profile:   https://github.com/react-foundation-bot
─────────────────────────────────────

🎉 Bot is ready to use!

How Issues Look Now

Issues filed by the bot include clear attribution:

> **Filed by [@username](https://github.com/username)** via [React Foundation Store](https://react.foundation)

[Issue content...]

---
from-chatbot · bug

Next Steps After Merge

1. Add GITHUB_BOT_TOKEN to production environment variables
2. Users will automatically get reduced OAuth scope on next login
3. Start using useGitHubBot() hook in components that need to file issues

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
react-foundation	Building	Preview	Comment	Oct 28, 2025 9:01pm

[claude]

Pull Request Review: GitHub Bot Implementation

Overall Assessment: Approve with Minor Suggestions

This is a well-implemented feature that significantly improves security and UX by reducing OAuth scope requirements. The code quality is excellent with comprehensive error handling, proper TypeScript typing, and thorough documentation.

---

Strengths

Architecture and Design

• Excellent separation of concerns: Bot service, API endpoint, and React hook are cleanly separated
• Clear attribution system: Issues filed by the bot include proper user attribution via markdown quotes
• Reduced OAuth scope: From public_repo to just read:user user:email - major security win
• Well-documented: Comprehensive setup guide with troubleshooting section

Code Quality

• Strong TypeScript typing: All interfaces properly defined, no any types used
• Comprehensive error handling: Covers 404, 403, 410, 401, and 503 errors with clear messages
• Input validation: Thorough validation in API endpoint (lines 42-90 in route.ts)
• Clean error messages: User-friendly error messages that guide users to solutions

Security

• Proper authentication checks: Validates user session before allowing issue filing
• Rate limiting awareness: Documentation mentions GitHubs 5,000 req/hour limit
• Token security: Clear instructions to never commit tokens, rotate periodically

---

Issues and Suggestions

1. SECURITY: Missing Rate Limiting Implementation (High Priority)

Location: src/app/api/bot/file-issue/route.ts

Issue: The API endpoint has no rate limiting, allowing authenticated users to spam GitHub with issues. The documentation mentions rate limiting but doesnt implement it.

Recommendation: Add rate limiting using a RateLimiter utility (5 requests per hour per user recommended)

2. SECURITY: Missing Repository Whitelist (Medium Priority)

Location: src/app/api/bot/file-issue/route.ts:93-104

Issue: Users can file issues to ANY public repository, not just React Foundation repos. This could be abused to spam other projects.

Recommendation: Add a whitelist of allowed repositories (facebook/react, sethwebster/react-foundation, etc.)

3. BUG: Console.log in Production Code (Low Priority)

Location: src/app/api/bot/file-issue/route.ts:117

Issue: Using console.error instead of the logger. According to CLAUDE.md NO console.log

Recommendation: Replace with logger.error from @/lib/logger

4. TypeScript: Potential Type Safety Issue (Low Priority)

Location: src/app/api/bot/file-issue/route.ts:101

Issue: Fallback to Unknown could cause attribution issues. Should require githubLogin or name.

Recommendation: Validate that at least one identifier is available before proceeding

5. Testing: Missing Error Case Tests (Low Priority)

Location: scripts/test-bot.ts

Issue: Test script only validates successful connection, doesnt test actual issue creation.

Recommendation: Add optional test issue creation to verify end-to-end functionality

6. Documentation: Missing Environment Setup Order (Low Priority)

Location: docs/development/github-bot-setup.md

Suggestion: Add a note that the bot token should be added to production environment BEFORE merging, otherwise the API will return 503 errors immediately after deployment.

7. Code Quality: Validation Could Be More DRY (Low Priority)

Location: src/app/api/bot/file-issue/route.ts:42-90

Suggestion: Extract validation logic to use Zod (already in codebase) for consistency and reduced boilerplate

---

Checklist Review (per CLAUDE.md)

• TypeScript passes: No visible TypeScript errors (types properly defined)
• No any types: All types are properly defined
• Proper interfaces: FileIssueParams, FiledIssueResult, etc. all well-defined
• Error handling: Comprehensive error handling throughout
• Next.js patterns: Proper App Router usage, server components
• Code structure: Clean separation of concerns
• Console.log usage: One instance at line 117 (should use logger)
• Rate limiting: Not implemented (documented but not coded) - CRITICAL
• Repository whitelist: Not implemented (security concern) - CRITICAL

---

Impact Analysis

Positive Impacts:

• Security: Users no longer grant write access to all repositories
• Trust: Much less intimidating OAuth prompt increases conversion
• Control: Centralized bot allows monitoring, rate limiting, moderation
• Audit Trail: All actions attributed and logged
• UX: Chatbot integration is cleaner and less confusing

Risk Mitigation Needed:

• Spam Prevention: Add rate limiting before production deployment
• Abuse Prevention: Add repository whitelist to prevent spam to other projects
• Monitoring: Add logging/monitoring for bot actions in production

---

Recommendations for Merge

Before Merging (CRITICAL):

1. Implement rate limiting (5 issues/hour per user recommended)
2. Add repository whitelist to prevent abuse
3. Replace console.error with logger.error (line 117)
4. Add GITHUB_BOT_TOKEN to production environment variables

Nice to Have (Can be follow-up PRs):

1. Extract validation to Zod schema for consistency
2. Add test issue creation to test script
3. Consider adding content moderation (spam keyword filtering)
4. Add metrics/monitoring for bot usage

---

Summary

This is a high-quality implementation that delivers significant value. The architecture is sound, code is well-written, and documentation is thorough.

The main concerns are security-related (missing rate limiting and repository whitelist) which should be addressed before production deployment. These are straightforward to implement and would make this feature production-ready.

Recommendation: Approve with required changes

• Implement rate limiting (CRITICAL)
• Add repository whitelist (CRITICAL)
• Replace console.error with logger (IMPORTANT)

Once these are addressed, this is ready to merge and will be a great improvement to the user experience and security posture of the React Foundation Store.

Great work!