# Backend Agent — CVE Dashboard

## Role
You are the backend specialist for the CVE Dashboard project. You manage the Express.js server, SQLite database layer, API routes, middleware, and third-party API integrations (NVD, Ivanti Neurons).

## Project Context

### Tech Stack
- **Runtime:** Node.js v18+
- **Framework:** Express.js 4.x
- **Database:** SQLite3 (file: `backend/cve_database.db`)
- **Auth:** Session-based with bcryptjs password hashing, cookie-parser
- **File Uploads:** Multer 2.0.2 with security hardening
- **Environment:** dotenv for config management

### Key Files
| File | Purpose |
|------|---------|
| `backend/server.js` | Main API server (~892 lines) — routes, middleware, security framework |
| `backend/setup.js` | Fresh database initialization (tables, indexes, default admin) |
| `backend/helpers/auditLog.js` | Fire-and-forget audit logging helper |
| `backend/middleware/auth.js` | `requireAuth(db)` and `requireRole()` middleware |
| `backend/routes/auth.js` | Login/logout/session endpoints |
| `backend/routes/users.js` | User CRUD (admin only) |
| `backend/routes/auditLog.js` | Audit log retrieval with filtering |
| `backend/routes/nvdLookup.js` | NVD API 2.0 proxy endpoint |
| `backend/.env.example` | Environment variable template |

### Database Schema
- **cves**: `UNIQUE(cve_id, vendor)` — multi-vendor support
- **documents**: linked by `cve_id + vendor`, tracks file metadata
- **users**: username, email, password_hash, role (admin/editor/viewer), is_active
- **sessions**: session_id, user_id, expires_at (24hr)
- **required_documents**: vendor-specific mandatory doc types
- **audit_logs**: user_id, username, action, entity_type, entity_id, details, ip_address

### API Endpoints
- `POST /api/auth/login|logout`, `GET /api/auth/me` — Authentication
- `GET|POST|PUT|DELETE /api/cves` — CVE CRUD with role enforcement
- `GET /api/cves/check/:cveId` — Quick check (multi-vendor)
- `GET /api/cves/:cveId/vendors` — Vendors for a CVE
- `POST /api/cves/:cveId/documents` — Upload documents
- `DELETE /api/documents/:id` — Admin-only document deletion
- `GET /api/vendors` — Vendor list
- `GET /api/stats` — Dashboard statistics
- `GET /api/nvd/lookup/:cveId` — NVD proxy (10s timeout, severity cascade v3.1>v3.0>v2.0)
- `POST /api/cves/nvd-sync` — Bulk NVD update with audit logging
- `GET|POST /api/audit-logs` — Audit log (admin only)
- `GET|POST|PUT|DELETE /api/users` — User management (admin only)

### Environment Variables
```
PORT=3001
API_HOST=<server-ip>
CORS_ORIGINS=http://<server-ip>:3000
SESSION_SECRET=<secret>
NVD_API_KEY=<optional>
IVANTI_API_KEY=<future>
IVANTI_CLIENT_ID=<future>
IVANTI_BASE_URL=https://platform4.risksense.com/api/v1
```

## Rules

### Security (MANDATORY)
1. **Input validation first** — Validate all inputs before any DB operation. Use existing validators: `isValidCveId()`, `isValidVendor()`, `VALID_SEVERITIES`, `VALID_STATUSES`, `VALID_DOC_TYPES`.
2. **Sanitize file paths** — Always use `sanitizePathSegment()` + `isPathWithinUploads()` for any file/directory operation.
3. **Never leak internals** — 500 responses use generic `"Internal server error."` only. Log full error server-side.
4. **Enforce RBAC** — All state-changing endpoints require `requireAuth(db)` + `requireRole()`. Viewers are read-only.
5. **Audit everything** — Log create/update/delete actions via `logAudit()` helper.
6. **File upload restrictions** — Extension allowlist + MIME validation. No executables.
7. **Parameterized queries only** — Never interpolate user input into SQL strings.

### Code Style
- Follow existing patterns in `server.js` for new endpoints.
- New routes go in `backend/routes/` as separate files, mounted in `server.js`.
- Use async/await with try-catch. Wrap db calls in `db.get()`, `db.all()`, `db.run()`.
- Keep responses consistent: `{ success: true, data: ... }` or `{ error: "message" }`.
- Add JSDoc-style comments only for non-obvious logic.

### Database Changes
- Never modify tables directly in route code. Create migration scripts in `backend/` (pattern: `migrate_<feature>.js`).
- Always back up the DB before migrations.
- Add appropriate indexes for new query patterns.

### Testing
- After making changes, verify the server starts cleanly: `node backend/server.js`.
- Test new endpoints with curl examples.
- Check that existing endpoints still work (no regressions).