mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-08-02 21:32:10 +03:00
1cbbc33f20
FASE-01 — Security Hardening: - Remove hardcoded JWT_SECRET and API_KEY_SECRET fallbacks (fail-fast) - Create secretsValidator.js with enforceSecrets() at startup - Create inputSanitizer.js (prompt injection + PII detection) - Integrate sanitizer in chat.js handler pipeline - Add structured logging to silent catch blocks in proxy.js - Remove .passthrough() from Zod updateSettingsSchema - Remove insecure npm fs dependency - Update .env.example with generation commands FASE-02 — CI/CD & Tests: - Create ci.yml workflow (lint, build, test, coverage, e2e) - Fix test scripts (test now runs actual tests) - Add test:unit, test:security, test:coverage (c8), test:all - Add security rules to ESLint (no-eval, no-implied-eval, no-new-func) FASE-03 — Architecture: - Create settingsCache.js (eliminate self-fetch anti-pattern) - Create domain/types.js and domain/responses.js FASE-04 — Observability: - Create correlationId.js (AsyncLocalStorage tracing) - Create circuitBreaker.js (full state machine + registry) - Create requestTimeout.js (per-provider timeouts) FASE-05 — Code Quality: - Create structuredLogger.js (JSON/human-readable logging) FASE-06 — Documentation: - Update SECURITY.md with hardening practices - Create CONTRIBUTING.md with dev setup and PR checklist Tests: 52/52 pass (23 security + 15 observability + 14 integration)
113 lines
2.9 KiB
Markdown
113 lines
2.9 KiB
Markdown
# Contributing to OmniRoute
|
|
|
|
Thank you for your interest in contributing! This guide will help you get started.
|
|
|
|
## Development Setup
|
|
|
|
```bash
|
|
# Clone and install
|
|
git clone https://github.com/diegosouzapw/OmniRoute.git
|
|
cd OmniRoute
|
|
npm install
|
|
|
|
# Create your .env from the template
|
|
cp .env.example .env
|
|
|
|
# Generate required secrets
|
|
echo "JWT_SECRET=$(openssl rand -base64 48)" >> .env
|
|
echo "API_KEY_SECRET=$(openssl rand -hex 32)" >> .env
|
|
|
|
# Start development server
|
|
npm run dev
|
|
```
|
|
|
|
## Git Workflow
|
|
|
|
> ⚠️ **NEVER commit directly to `main`.** Always use feature branches.
|
|
|
|
```bash
|
|
git checkout -b feat/your-feature-name
|
|
# ... make changes ...
|
|
git commit -m "feat: describe your change"
|
|
git push -u origin feat/your-feature-name
|
|
# Open a Pull Request on GitHub
|
|
```
|
|
|
|
### Branch Naming
|
|
|
|
| Prefix | Purpose |
|
|
| ----------- | ------------------------- |
|
|
| `feat/` | New features |
|
|
| `fix/` | Bug fixes |
|
|
| `refactor/` | Code restructuring |
|
|
| `docs/` | Documentation changes |
|
|
| `test/` | Test additions/fixes |
|
|
| `chore/` | Tooling, CI, dependencies |
|
|
|
|
### Commit Messages
|
|
|
|
Follow [Conventional Commits](https://www.conventionalcommits.org/):
|
|
|
|
```
|
|
feat: add circuit breaker for provider calls
|
|
fix: resolve JWT secret validation edge case
|
|
docs: update SECURITY.md with PII protection
|
|
test: add observability unit tests
|
|
```
|
|
|
|
## Running Tests
|
|
|
|
```bash
|
|
# All unit tests
|
|
npm test
|
|
|
|
# Specific test suites
|
|
npm run test:security # FASE-01 security tests
|
|
npm run test:fixes # Fix verification tests
|
|
|
|
# With coverage
|
|
npm run test:coverage
|
|
|
|
# E2E tests (requires Playwright)
|
|
npm run test:e2e
|
|
|
|
# Lint + test
|
|
npm run check
|
|
```
|
|
|
|
## Code Style
|
|
|
|
- **ESLint** — Run `npm run lint` before committing
|
|
- **Prettier** — Auto-formatted via `lint-staged` on commit
|
|
- **JSDoc** — Document public functions with `@param`, `@returns`, `@throws`
|
|
- **No `eval()`** — ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func`
|
|
|
|
## Architecture Overview
|
|
|
|
```
|
|
src/
|
|
├── app/ # Next.js pages and API routes
|
|
├── domain/ # Domain types and response helpers
|
|
├── lib/ # Database, OAuth, and core logic
|
|
├── shared/
|
|
│ ├── middleware/ # Correlation IDs, etc.
|
|
│ ├── utils/ # Sanitizer, circuit breaker, etc.
|
|
│ └── validation/ # Zod schemas
|
|
└── sse/ # SSE chat handlers and services
|
|
```
|
|
|
|
## Adding a New Provider
|
|
|
|
1. Create `src/lib/oauth/services/your-provider.js` extending `OAuthService`
|
|
2. Register in `src/lib/oauth/providers.js`
|
|
3. Add timeout in `src/shared/utils/requestTimeout.js`
|
|
4. Add tests in `tests/unit/`
|
|
|
|
## Pull Request Checklist
|
|
|
|
- [ ] Tests pass (`npm test`)
|
|
- [ ] Linting passes (`npm run lint`)
|
|
- [ ] JSDoc added for new public functions
|
|
- [ ] No hardcoded secrets or fallback values
|
|
- [ ] CHANGELOG updated (if user-facing change)
|