fix(api): rate limit stats refresh bypass (JhaSourav07#3278)

## Description

Fixes JhaSourav07#3196

This adds the same manual refresh protections used by `/api/github` to
the public `/api/stats` endpoint. Before this, `/api/stats?refresh=true`
passed `bypassCache: true` straight into `fetchGitHubContributions`, so
repeated stats refreshes could force fresh GitHub contribution fetches
without checking shared quota, client refresh limits, or per-user
cooldown.

## Pillar

- [x] 🛠️ Other (Bug fix, refactoring, docs)

## What changed

- Added low-quota blocking for stats refreshes.
- Added client IP refresh rate limiting for `/api/stats?refresh=true`.
- Added per-user refresh cooldown fallback so repeated refreshes use
cached stats instead of bypassing cache.
- Added `X-Refresh-Status` for `Fresh`, `Cached`, and
`Cooldown-Served-Cached` responses.
- Added regression tests for fresh refresh, cooldown fallback, rate
limit rejection, and low quota rejection.

## GSSoC 2026

This PR is raised as part of GSSoC 2026. The linked issue is assigned to
me but still has no labels after the earlier `/addlabel` command, so
please add the relevant GSSoC/type labels if they are not applied
automatically.

## Visual Preview

N/A - API behavior/header change only.

## Validation

```bash
npm run test -- app/api/stats/route.test.ts
npm run format
npm run format:check
npm run lint
npm run typecheck
```

`npm run lint` passes with existing warnings outside this change. I also
tried `npm run build` locally, but this environment only returned Next's
generic `Build failed because of webpack errors` message without
file-level diagnostics; previous GitHub CI production builds have been
the reliable signal for this repo.

## Checklist before requesting a review:

- [x] I have read the `CONTRIBUTING.md` file.
- [x] I have tested these changes locally
(`localhost:3000/api/streak?user=YOUR_USERNAME`).
- [x] I have run `npm run format` and `npm run lint` locally and
resolved all errors.
- [x] My commits follow the Conventional Commits format.
- [x] I have updated `README.md` if I added a new theme or URL
parameter.
- [x] I have starred the repo.
- [x] I have made sure that I have only one commit to merge in this PR.
- [x] The SVG output matches the CommitPulse quality standard.

Author: JhaSourav07

app/api/stats/route.test.ts

@@ -7,6 +7,9 @@ vi.mock('../../../lib/github', () => ({
 
 import { fetchGitHubContributions } from '../../../lib/github';
 import type { ContributionCalendar } from '../../../types';
+import { quotaMonitor } from '@/services/github/quota-monitor';
+import { refreshPolicy } from '@/services/github/refresh-policy';
+import { refreshRateLimiter } from '@/services/github/refresh-rate-limiter';
 
 // Calendar with a known, predictable streak so assertions are deterministic.
 // Last day (2024-06-16) has commits; "today" in tests is set to that date.
@@ -27,17 +30,25 @@ const mockCalendar: ContributionCalendar = {
   ],
 };
 
-function makeRequest(params: Record<string, string> = {}): Request {
+function makeRequest(
+  params: Record<string, string> = {},
+  headers: Record<string, string> = {}
+): Request {
   const url = new URL('http://localhost/api/stats');
   for (const [key, value] of Object.entries(params)) {
     url.searchParams.set(key, value);
   }
-  return new Request(url.toString());
+  return new Request(url.toString(), {
+    headers: new Headers(headers),
+  });
 }
 
 describe('GET /api/stats', () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    quotaMonitor.reset();
+    refreshPolicy.reset();
+    refreshRateLimiter.reset();
     vi.mocked(fetchGitHubContributions).mockResolvedValue({
       calendar: mockCalendar,
       repoContributions: [],
@@ -110,6 +121,7 @@ describe('GET /api/stats', () => {
     expect(response.headers.get('Cache-Control')).toBe('no-store, no-cache, must-revalidate');
     expect(response.headers.get('Pragma')).toBe('no-cache');
     expect(response.headers.get('Expires')).toBe('0');
+    expect(response.headers.get('X-Refresh-Status')).toBe('Fresh');
   });
 
   it('still returns valid stats data when refresh=true', async () => {
@@ -143,6 +155,47 @@ describe('GET /api/stats', () => {
     expect(fetchGitHubContributions).toHaveBeenCalledWith('testuser', { bypassCache: false });
   });
 
+  it('serves cached stats instead of bypassing cache during refresh cooldown', async () => {
+    await GET(makeRequest({ user: 'testuser', refresh: 'true' }));
+
+    const response = await GET(makeRequest({ user: 'testuser', refresh: 'true' }));
+
+    expect(response.status).toBe(200);
+    expect(fetchGitHubContributions).toHaveBeenLastCalledWith('testuser', {
+      bypassCache: false,
+    });
+    expect(response.headers.get('X-Refresh-Status')).toBe('Cooldown-Served-Cached');
+    expect(response.headers.get('Cache-Control')).toBe(
+      'public, s-maxage=3600, stale-while-revalidate=86400'
+    );
+  });
+
+  it('returns 429 when stats refresh exceeds the client refresh rate limit', async () => {
+    refreshRateLimiter.setLimit(1);
+
+    await GET(makeRequest({ user: 'testuser', refresh: 'true' }, { 'x-real-ip': '203.0.113.9' }));
+
+    const response = await GET(
+      makeRequest({ user: 'octocat', refresh: 'true' }, { 'x-real-ip': '203.0.113.9' })
+    );
+
+    expect(response.status).toBe(429);
+    const body = await response.json();
+    expect(body.error).toContain('Refresh rate limit exceeded');
+    expect(response.headers.get('X-RateLimit-Limit')).toBe('1');
+  });
+
+  it('blocks stats refresh when the shared GitHub quota is low', async () => {
+    quotaMonitor.setQuota(5000, 400, Date.now() + 60_000);
+
+    const response = await GET(makeRequest({ user: 'testuser', refresh: 'true' }));
+
+    expect(response.status).toBe(429);
+    const body = await response.json();
+    expect(body.error).toContain('quota is low');
+    expect(fetchGitHubContributions).not.toHaveBeenCalled();
+  });
+
   it('accepts a valid IANA timezone without error', async () => {
     const response = await GET(makeRequest({ user: 'testuser', tz: 'America/New_York' }));
     expect(response.status).toBe(200);

app/api/stats/route.ts

@@ -3,6 +3,21 @@ import { NextResponse } from 'next/server';
 import { fetchGitHubContributions } from '@/lib/github';
 import { calculateStreak } from '@/lib/calculate';
 import { statsParamsSchema } from '@/lib/validations';
+import { getClientIp } from '@/utils/getClientIp';
+import { quotaMonitor } from '@/services/github/quota-monitor';
+import { refreshPolicy } from '@/services/github/refresh-policy';
+import { refreshRateLimiter } from '@/services/github/refresh-rate-limiter';
+
+function logSecurityEvent(event: string, details: Record<string, unknown>) {
+  console.warn(
+    JSON.stringify({
+      timestamp: new Date().toISOString(),
+      type: 'SECURITY_EVENT',
+      event,
+      ...details,
+    })
+  );
+}
 
 /**
  * GET /api/stats?user=<username>[&refresh=true][&tz=<IANA timezone>]
@@ -20,6 +35,7 @@ import { statsParamsSchema } from '@/lib/validations';
  */
 export async function GET(request: Request) {
   const { searchParams } = new URL(request.url);
+  const ip = getClientIp(request);
 
   const parseResult = statsParamsSchema.safeParse(Object.fromEntries(searchParams.entries()));
 
@@ -47,6 +63,54 @@ export async function GET(request: Request) {
 
   const { user, refresh, tz } = parseResult.data;
 
+  if (refresh && quotaMonitor.isQuotaLow()) {
+    logSecurityEvent('LOW_QUOTA_STATS_REFRESH_BLOCKED', {
+      user,
+      ip,
+      remainingQuota: quotaMonitor.getQuota().remaining,
+    });
+    return NextResponse.json(
+      { error: 'GitHub API quota is low. Stats refresh temporarily disabled.' },
+      { status: 429 }
+    );
+  }
+
+  if (refresh) {
+    const rateLimitCheck = refreshRateLimiter.checkLimit(ip);
+    if (!rateLimitCheck.success) {
+      logSecurityEvent('STATS_REFRESH_RATE_LIMIT_EXCEEDED', {
+        user,
+        ip,
+        limit: rateLimitCheck.limit,
+      });
+      return NextResponse.json(
+        { error: 'Refresh rate limit exceeded. Please try again later.' },
+        {
+          status: 429,
+          headers: {
+            'X-RateLimit-Limit': rateLimitCheck.limit.toString(),
+            'X-RateLimit-Remaining': rateLimitCheck.remaining.toString(),
+            'X-RateLimit-Reset': rateLimitCheck.reset.toString(),
+          },
+        }
+      );
+    }
+  }
+
+  let shouldBypassCache = refresh;
+  if (refresh) {
+    if (!refreshPolicy.isRefreshAllowed(user)) {
+      logSecurityEvent('STATS_REFRESH_COOLDOWN_VIOLATION', {
+        user,
+        ip,
+        remainingMs: refreshPolicy.getRemainingCooldown(user),
+      });
+      shouldBypassCache = false;
+    } else {
+      refreshPolicy.recordRefresh(user);
+    }
+  }
+
   // Validate the optional IANA timezone early so callers get a clear 400
   // rather than a silent fallback or a 500.
   let timezone = 'UTC';
@@ -59,19 +123,23 @@ export async function GET(request: Request) {
   }
 
   try {
-    const userData = await fetchGitHubContributions(user, { bypassCache: refresh });
+    const userData = await fetchGitHubContributions(user, { bypassCache: shouldBypassCache });
     const calendar = userData.calendar;
     const stats = calculateStreak(calendar, timezone);
     const headers = new Headers({
       // Cache until next UTC midnight; clients can bust with ?refresh=true
       'Cache-Control': 'public, s-maxage=3600, stale-while-revalidate=86400',
     });
 
-    if (refresh) {
+    if (shouldBypassCache) {
       headers.set('Cache-Control', 'no-store, no-cache, must-revalidate');
       headers.set('Pragma', 'no-cache');
       headers.set('Expires', '0');
     }
+    headers.set(
+      'X-Refresh-Status',
+      shouldBypassCache ? 'Fresh' : refresh ? 'Cooldown-Served-Cached' : 'Cached'
+    );
 
     return NextResponse.json(
       {