fix: enforce ownership and disable caching for AI endpoint

.env.example

@@ -35,3 +35,8 @@ GITHUB_APP_STATE_SECRET=
 
 # Optional: For client-side API calls
 NEXT_PUBLIC_API_URL=http://localhost:3000
+
+
+# Rate Limiting (In-Memory)
+RATE_LIMIT_WINDOW_MS=900000 # 15 minutes in milliseconds
+RATE_LIMIT_MAX_REQUESTS=5   # Max attempts per window

GETTING_STARTED.md

@@ -4,7 +4,7 @@ This is the Next.js version of GitVerse, migrated from the Vite + React version
 
 ## Prerequisites
 
-- Node.js 18+ installed
+- Node.js 22.x installed (see [Supported Node Version](README.md#supported-node-version))
 - PostgreSQL database (NeonDB recommended)
 - Google Gemini AI API key
 
@@ -28,13 +28,13 @@ cp .env.example .env.local
 Edit `.env.local` and fill in your values:
 
 ```env
-# Database - Get from https://neon.tech
+# Database - Get from [https://neon.tech](https://neon.tech)
 DATABASE_URL=postgresql://user:password@host/database?sslmode=require&schema=public
 
 # JWT Secret - Generate a secure random string
 JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
 
-# Gemini AI - Get from https://makersuite.google.com/app/apikey
+# Gemini AI - Get from [https://makersuite.google.com/app/apikey](https://makersuite.google.com/app/apikey)
 GEMINI_API_KEY=your_gemini_api_key_here
 
 # NextAuth (required for Google login)
@@ -47,7 +47,7 @@ GOOGLE_CLIENT_SECRET=your-google-client-secret
 
 # Optional: Base URL for API calls
 # Leave unset to use same-origin `/api/...` (recommended).
-# If you set it, avoid a trailing slash (e.g. https://example.com, not https://example.com/)
+# If you set it, avoid a trailing slash (e.g. [https://example.com](https://example.com), not [https://example.com/](https://example.com/))
 # NEXT_PUBLIC_API_URL=http://localhost:3000
 ```
 
@@ -108,13 +108,23 @@ Open [http://localhost:3000](http://localhost:3000) in your browser.
 
 ### Running the App
 
+Note on Background Tasks: For standard local development, background tasks are handled seamlessly by Next.js API routes. The legacy worker script is optional and generally not required.
+
 ```bash
 npm run dev          # Development server
 npm run build        # Production build
 npm start            # Production server
 npm run lint         # Lint code
 ```
 
+### Legacy Worker (Optional)
+
+If you are testing specific background workflows locally that mimic a custom non-serverless deployment, you can optionally run the worker:
+
+```bash
+npm run worker       # Run background tasks (Legacy / Optional)
+```
+
 ### Database Management
 
 ```bash
@@ -166,23 +176,31 @@ All endpoints are prefixed with `/api`:
 
 ### Vercel (Recommended)
 
+Vercel automatically handles background processes via serverless functions, so the worker script is not needed for this deployment method.
+
 1. Push code to GitHub
 2. Import in Vercel dashboard
 3. Add environment variables
 4. Deploy automatically
 
 ### Docker
+If self-hosting via Docker, run the primary application container. If your deployment uses queue-based background processing, run the legacy worker as a separate process/container.
 
 ```bash
 docker build -t gitverse-nextjs .
 docker run -p 3000:3000 gitverse-nextjs
 ```
 
 ### Manual Deployment
+For deployments on custom servers (e.g., EC2, VPS) where serverless functions aren't available, run the app build. If queue-based background processing is enabled, also run the worker script (for example via PM2/systemd).
 
 ```bash
 npm run build
 npm start
+
+# In a separate terminal or using a process manager like PM2:
+npm run worker
+
 ```
 
 ## Troubleshooting

GIT_GRAPH_SETUP.md

@@ -79,3 +79,35 @@ The graph algorithm uses these parent relationships to:
 - Detect when branches merge
 - Position commits in the correct columns
 - Show branch splits and joins
+
+## Security & Access Control
+
+To protect private repository data and analysis results, GitVerse enforces strict ownership and caching rules across all user-scoped API endpoints.
+
+### Ownership Enforcement Strategy
+
+Before returning sensitive data (e.g., repository insights or commit history), the backend middleware must validate that the authenticated user actually owns the requested resource.
+- **Authorized:** If `repository.userId === user.id`, the data is safely returned.
+- **Unauthorized (404/403):** If a user attempts to access another user's private data, the API will intentionally return a generic `404 Not Found` or `403 Forbidden` to prevent leaking the existence or metadata of private resources.
+
+### Cache-Control: `no-store`
+
+All endpoints returning private or user-scoped data explicitly define HTTP caching directives to prevent accidental data leakage via proxies or browsers.
+
+**Example Response Header:**
+```http
+Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate
+```
+
+This guarantees that:
+- Browsers never cache sensitive repository data.
+- CDNs or edge proxies do not mistakenly serve one user's data to another.
+- API requests always hit the origin server to re-verify authentication and ownership.
+
+### Best Practices for Protected Endpoints
+
+When developing new GitVerse API routes, always adhere to the following pattern:
+1. Extract and validate the session `user`.
+2. Fetch the resource and perform an ownership check.
+3. Return `404 Not Found` if the ownership check fails.
+4. Append `Cache-Control: no-store` to the `NextResponse` before returning.

GOOGLE_OAUTH_SETUP.md

@@ -120,6 +120,37 @@ When deploying to production:
 3. Ensure all environment variables are set in your production environment
 4. Run the database migration in production
 
+## Provider Rate Limits & Retry Strategies
+
+When GitVerse integrates with third-party providers (like GitHub or Google), it natively handles rate limiting and transient failures to ensure robust operation.
+
+### Rate Limit Behavior (HTTP 429)
+
+If a provider returns a `429 Too Many Requests` response, GitVerse will safely catch the error and surface a standardized response to the client. The frontend will typically display a message like:
+`"Rate limit reached. Please retry after X seconds."`
+
+GitVerse extracts the `retryAfter` or reset timing directly from the provider's HTTP headers and propagates it safely without exposing internal API responses.
+
+### Retry with Exponential Backoff
+
+For transient network failures or safe server errors (e.g., `502`, `503`, `504`), GitVerse employs an automatic exponential backoff mechanism.
+
+**Retry Flow Example:**
+- Attempt 1: Immediate Execution
+- Attempt 2: 1s delay
+- Attempt 3: 2s delay
+- Attempt 4: 4s delay
+
+This prevents infinite retry loops and respects provider rate limits while improving overall system reliability.
+
+## Secure Logging Practices
+
+To protect sensitive information, GitVerse enforces strict token sanitization requirements across all provider integrations:
+
+1. **Token Redaction:** Never log raw OAuth access tokens, `Authorization` headers, or provider credentials.
+2. **Error Sanitization:** If an HTTP fetch fails, the underlying `AxiosError` or `fetch` error is sanitized to strip out sensitive config and request headers before it reaches `console.error`.
+3. **Safe Debugging:** Logs will output the HTTP status code, safe message strings, and endpoint paths (excluding query string secrets) to preserve debuggability without compromising security.
+
 ## Troubleshooting
 
 ### Error: "redirect_uri_mismatch"