Repo-Ring

A Chrome extension for viewing GitHub notifications with secure token management

Features

• 🔔 Auto-Refresh: Background polling every 5 minutes for latest notifications
• ⚡ Instant Display: Cached notifications load immediately
• 🔄 Manual Refresh: On-demand refresh with 60-second cooldown
• 📊 Read/Unread Badges: Visual indicators for notification status
• 🕐 Last Fetch Time: Know when notifications were last updated
• 🔄 Auto-Retry: Exponential backoff retry mechanism for failed requests
• 🛡️ Error Handling: Graceful fallback to cached data on network errors
• 🔐 Secure Storage: AES-encrypted GitHub token storage
• 🎯 Badge Counter: Extension badge shows unread notification count
• 📱 Clean UI: Modern, GitHub-inspired interface
• ⏰ Smart Time: Relative time formatting (2m, 3h, 1d ago)
• 🎨 Contextual Icons: Different icons for issues, PRs, mentions, etc.
• 🚀 One-Click Access: Direct navigation to GitHub notifications

Quick Start

Installation

Option 1: From Source (Development)

1. Clone the repository

   git clone https://github.com/asifjoardar/RepoRing.git
   cd RepoRing

2. Install dependencies

   npm install

3. Build the extension

   npm run build

4. Load in Chrome

   • Open chrome://extensions/
   • Enable "Developer mode"
   • Click "Load unpacked"
   • Select the dist folder

Option 2: Chrome Web Store (Coming Soon)

Extension is being prepared for Chrome Web Store submission

Setup GitHub Token

Important: Only Classic Personal Access Tokens are supported. Fine-grained tokens are not compatible.

1. Go to GitHub Settings > Personal Access Tokens
2. Click "Generate new token" → "Generate new token (classic)"
3. Give it a name (e.g., "Repo-Ring Extension")
4. Select only these scopes:
   • ✅ notifications - Access notifications
   • ✅ read:user - Read user profile
5. Click "Generate token" and copy it (should start with ghp_)
6. Open Repo-Ring extension and paste your token

Security Note: The extension validates that tokens have only the minimal required permissions and will reject tokens with excessive scopes.

How It Works

Background Polling

• Automatically fetches notifications every 5 minutes
• Updates badge count for unread notifications
• Caches latest 5 notifications

Manual Refresh

• Click "Refresh" button for instant updates
• 60-second cooldown prevents API rate limiting
• Countdown timer shows when you can refresh again

Smart Caching

• Cached notifications display instantly on popup open
• No waiting for API calls
• Automatic cache updates from background worker

Retry Mechanism

• Network failures automatically retry 3 times
• Exponential backoff: 1s → 2s → 4s delays
• Smart error detection (won't retry auth errors)

Screenshots

Token Setup

Secure token setup with clear permission requirements

Notifications View

Clean notification list with read/unread indicators and manual refresh

Settings

Token management - update or remove your token anytime

Development

Prerequisites

• Node.js 16+ and npm
• Chrome browser
• Git

Development Build

npm run dev          # Build with watch mode
npm run build        # Production build
npm run type-check   # TypeScript validation

Project Structure

src/
├── components/          # React components
│   ├── Header.tsx      # Extension header
│   ├── NotificationItem.tsx
│   ├── NotificationList.tsx
│   └── TokenSetup.tsx
├── utils/              # Utilities
│   ├── githubApi.ts    # GitHub API client
│   ├── tokenStorage.ts # Secure token storage
│   ├── retry.ts        # Retry mechanism
│   └── helpers.ts      # Helper functions
├── background.ts       # Service worker
├── App.tsx             # Main app
├── popup.tsx           # Entry point
└── styles.css          # Tailwind styles

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Release Process

Before creating any release:

1. Run the comprehensive OWASP security audit:

   • Go to Actions → Pre-Release OWASP Audit
   • Click "Run workflow" and enter version number
   • Wait for results (~2-3 minutes)

2. If audit passes ✅:

   • Create release tag
   • Audit report auto-generates

3. If audit fails ❌:

   • DO NOT create release
   • Fix security issues
   • Re-run audit

See SECURITY.md for detailed release workflow.

Security Audit

Repo-Ring follows industry-standard security practices and has been audited against:

• OWASP Top 10 Web Application Security Risks
• Chrome Extension Security Best Practices
• Secure Coding Guidelines

Automated Security: Security audits run automatically on every release via GitHub Actions.

Audit Results: ✅ 0 vulnerabilities found - See SECURITY_AUDIT_REPORT.md

For detailed security practices and vulnerability reporting, see SECURITY.md.

Security & Privacy

🔒 Your Token is Safe - We Take Security Seriously

Repo-Ring is designed with security and privacy as top priorities. Your GitHub token and data are completely safe:

How We Protect Your Token:

• AES-256 Encryption: Your token is encrypted before being stored locally
• Zero Server Communication: Your token NEVER leaves your device or gets sent to any third-party servers
• Direct GitHub API: Extension communicates only with official GitHub API (api.github.com)
• Minimal Permissions: Validates tokens have only required scopes (notifications, read:user)
• No Logging: Tokens are never written to console logs or error reports
• Local Storage Only: All data stays on your Chrome browser, encrypted

What We DON'T Do:

• ❌ We don't collect, store, or transmit your personal data
• ❌ We don't track your usage or behavior
• ❌ We don't use analytics or third-party services
• ❌ We don't show ads or monetize your data
• ❌ We don't have access to your repositories or code

Open Source & Transparent:

• 📖 100% open source - inspect every line of code
• 🔍 All code is publicly available on GitHub
• 🛡️ Community-reviewed security practices

Security Features

• AES Encryption: Tokens encrypted before storage
• Scope Validation: Ensures minimal permissions (rejects excessive scopes)
• HTTPS Only: All API calls use HTTPS
• No Logging: Tokens never logged to console
• Local Storage: All data stored locally in Chrome
• Token Type Validation: Only accepts Classic tokens for compatibility

Privacy Policy

Effective Date: January 3, 2025

Data Collection

Repo-Ring does NOT collect, transmit, or share any personal data. All data remains on your device.

Data Storage

• GitHub Token: Stored encrypted in Chrome's local storage
• Notifications: Cached locally for performance
• No Remote Storage: Nothing is sent to external servers

Third-Party Services

• GitHub API: Extension communicates directly with GitHub's API using your token
• No Analytics: No tracking or analytics services used
• No Ads: Extension is completely ad-free

Your Rights

• All data is stored locally on your device
• Uninstalling the extension removes all stored data
• You can remove your token anytime from settings

Contact

For privacy concerns: mdasifjoardar@gmail.com

Permissions Explained

Required Permissions

• storage: Cache notifications and store encrypted token
• activeTab: Open GitHub notification links
• alarms: Background polling every 5 minutes
• host: api.github.com: Fetch notifications from GitHub API

Why These Permissions?

• Minimal permissions for core functionality
• No access to browsing history or other tabs
• No access to other websites
• Cannot read or modify web pages

Troubleshooting

Extension Issues

• Not loading: Run npm run build to rebuild
• Icons missing: Icons are pre-generated in icons/ folder
• Build errors: Delete node_modules and run npm install

Token Issues

• Invalid token: Check if token is correct and hasn't expired
• Wrong permissions: Ensure token has only notifications and read:user
• Network errors: Check internet connection, extension will auto-retry

Notification Issues

• Not updating: Check if background polling is enabled
• All showing as unread: This is a GitHub API status, not a bug
• Badge not showing: Check Chrome's extension badge permissions

Feedback & Support

• Bug Reports: GitHub Issues
• Feature Requests: GitHub Issues
• Questions: Email
• Contribute: See CONTRIBUTING.md

Changelog

See CHANGELOG.md for version history.

License

MIT License - feel free to use this project for learning or building your own extensions!

Acknowledgments

• Built with React
• Styled with Tailwind CSS
• Icons inspired by GitHub's design language

---

Made with ❤️ by Md Asif Joardar

⭐ Star this repo if you find it helpful!