From 1918217449400d1699f3ed1e75ea1e8cd4f88e0d Mon Sep 17 00:00:00 2001 From: Claude Code Date: Sat, 5 Jul 2025 21:58:18 -0400 Subject: [PATCH] Update documentation with security and testing information MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README.md: - Add comprehensive API endpoint documentation with admin routes - Update security section with detailed protections and limits - Add rate limiting, input validation, and authentication details - Include testing information (125+ tests, 76% coverage) - Update technology stack with TypeScript and security features CLAUDE.md: - Add detailed testing coverage information - Document security features in API endpoints section - Update key design patterns with security-by-design and testing - Include input validation limits and rate limiting details - Clarify admin-only DELETE functionality Both files now accurately reflect: - Current security implementations - Comprehensive test suite - TypeScript architecture - Rate limiting and input validation - Admin authentication requirements 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CLAUDE.md | 42 +++++++++++++++++++++++++++++------------- README.md | 37 +++++++++++++++++++++++++++++++------ 2 files changed, 60 insertions(+), 19 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 996825e..ec31daf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -60,13 +60,19 @@ npm run watch-css ### Testing ```bash -# Run all tests +# Run all tests (125+ tests with TypeScript) npm test -# Run tests with coverage report +# Run tests with coverage report (76% overall coverage) npm run test:coverage ``` +**Test Coverage:** +- **Unit Tests:** Location/ProfanityWord models, DatabaseService, ProfanityFilterService +- **Integration Tests:** Public API routes, Admin API routes with authentication +- **Security Tests:** Rate limiting, input validation, authentication flows +- **Coverage:** 76% statements, 63% branches, 78% lines + ### Environment Setup Before running the application, you must configure environment variables: ```bash @@ -140,18 +146,27 @@ Multiple map implementations for flexibility: ### API Endpoints -Public endpoints: +**Public endpoints:** - `GET /api/config`: Returns MapBox token for frontend geocoding - `GET /api/locations`: Active locations (< 48 hours old or persistent) -- `POST /api/locations`: Submit new location report (with profanity filtering) +- `POST /api/locations`: Submit new location report (rate limited: 10/15min per IP) + - **Input Validation:** Address ≤500 chars, Description ≤1000 chars + - **Profanity Filtering:** Automatic content moderation with rejection + - **Security:** Rate limiting prevents spam and DoS attacks -Admin endpoints (require Bearer token): +**Admin endpoints (require Bearer token):** - `POST /api/admin/login`: Authenticate and receive token - `GET /api/admin/locations`: All locations including expired - `PUT /api/admin/locations/:id`: Update location details - `PATCH /api/admin/locations/:id/persistent`: Toggle persistent status -- `DELETE /api/admin/locations/:id`: Delete location -- Profanity management: `/api/admin/profanity-words` (GET, POST, PUT, DELETE) +- `DELETE /api/admin/locations/:id`: Delete location (admin-only) +- **Profanity management:** `/api/admin/profanity-words` (GET, POST, PUT, DELETE) + +**Security Features:** +- **Rate Limiting:** Express-rate-limit middleware on public endpoints +- **Authentication:** Bearer token authentication for admin routes +- **Input Validation:** Strict length limits and type checking +- **Audit Logging:** Suspicious activity detection and logging ### SCSS Organization SCSS files are in `src/scss/`: @@ -164,12 +179,13 @@ SCSS files are in `src/scss/`: ### Key Design Patterns 1. **TypeScript-First Architecture**: Full type safety with strict type checking -2. **Modular Route Architecture**: Routes accept dependencies as parameters for testability -3. **Dual Database Design**: Separate databases for application data and content moderation -4. **Type-Safe Database Operations**: All database interactions use typed models -5. **Graceful Degradation**: Fallback geocoding providers and error handling -6. **Automated Maintenance**: Cron-based cleanup of expired reports -7. **Security**: Server-side content filtering, environment-based configuration +2. **Security-by-Design**: Rate limiting, input validation, and authentication built into core routes +3. **Modular Route Architecture**: Routes accept dependencies as parameters for testability +4. **Dual Database Design**: Separate databases for application data and content moderation +5. **Type-Safe Database Operations**: All database interactions use typed models +6. **Comprehensive Testing**: 125+ tests covering units, integration, and security scenarios +7. **Graceful Degradation**: Fallback geocoding providers and error handling +8. **Automated Maintenance**: Cron-based cleanup of expired reports ### Deployment - Automated deployment script for Debian 12 ARM64 in `scripts/deploy.sh` diff --git a/README.md b/README.md index 8e54b37..0c93a50 100644 --- a/README.md +++ b/README.md @@ -114,16 +114,32 @@ See `docs/deployment.md` for detailed manual deployment instructions. ## API Endpoints +### Public Endpoints - `GET /api/locations` - Get active location reports -- `POST /api/locations` - Submit new location report +- `POST /api/locations` - Submit new location report (rate limited: 10/15min per IP) - `GET /api/config` - Get API configuration + +### Admin Endpoints (Authentication Required) - `GET /admin` - Admin panel (password protected) +- `GET /api/admin/locations` - Get all location reports +- `PUT /api/admin/locations/:id` - Update location report +- `PATCH /api/admin/locations/:id/persistent` - Toggle persistent status +- `DELETE /api/admin/locations/:id` - Delete location report +- `GET /api/admin/profanity-words` - Manage profanity filter +- `POST /api/admin/profanity-words` - Add custom profanity word +- `PUT /api/admin/profanity-words/:id` - Update profanity word +- `DELETE /api/admin/profanity-words/:id` - Delete profanity word + +### API Documentation +Interactive API documentation available at `/api-docs` when running the server. ## Technology Stack -- **Backend:** Node.js, Express.js, SQLite +- **Backend:** Node.js, Express.js, SQLite, TypeScript - **Frontend:** Vanilla JavaScript, Leaflet.js - **Geocoding:** MapBox API (with Nominatim fallback) +- **Security:** Rate limiting, input validation, authentication +- **Testing:** Jest, TypeScript, 125+ tests with 76% coverage - **Reverse Proxy:** Caddy (automatic HTTPS) - **Database:** SQLite (lightweight, serverless) @@ -137,10 +153,19 @@ See `docs/deployment.md` for detailed manual deployment instructions. ## Security -- API keys are stored in environment variables -- Admin routes are password protected -- Database queries use parameterized statements -- HTTPS enforced in production +- **Authentication:** Admin routes protected with bearer token authentication +- **Rate Limiting:** Public endpoints limited to prevent abuse (10 requests/15min per IP) +- **Input Validation:** Strict length limits and type checking on all user inputs +- **Data Protection:** API keys stored in environment variables only +- **Database Security:** Parameterized queries prevent SQL injection +- **Content Filtering:** Built-in profanity filter with custom word management +- **HTTPS:** Enforced in production via Caddy reverse proxy +- **Audit Logging:** Suspicious activity and abuse attempts are logged + +### Input Limits +- **Address:** Maximum 500 characters +- **Description:** Maximum 1000 characters +- **Submissions:** 10 per 15 minutes per IP address ## License