Initial commit

skills/api-design-standards/checklists/api-design-checklist.md

@@ -0,0 +1,118 @@
+# API Design Checklist
+
+**Use this checklist before creating PR for new API endpoints.**
+
+## RESTful Design
+
+- [ ] URLs use plural nouns (`/users` not `/user`)
+- [ ] URLs use lowercase with hyphens (`/user-profiles` not `/userProfiles`)
+- [ ] No verbs in URLs (`/users` not `/getUsers`)
+- [ ] Hierarchical resources follow pattern `/parent/{id}/child`
+- [ ] HTTP verbs used correctly (GET=read, POST=create, PUT=update, DELETE=delete)
+
+## Multi-Tenant Isolation
+
+- [ ] All queries filtered by `tenant_id` from JWT
+- [ ] Repository pattern used with automatic tenant filtering
+- [ ] No direct database queries bypassing repository
+- [ ] Cross-tenant access blocked (except superuser endpoints)
+- [ ] Test cases verify tenant isolation
+
+## Request/Response Schemas
+
+- [ ] Pydantic schemas defined for all requests
+- [ ] Pydantic schemas defined for all responses
+- [ ] Password hashes never returned in responses
+- [ ] Sensitive fields excluded from public schemas
+- [ ] Validation rules enforced (min/max length, format, etc.)
+- [ ] Field-level validation implemented where needed
+- [ ] Model-level validation for cross-field rules
+
+## HTTP Status Codes
+
+- [ ] 200 OK for successful GET/PUT/PATCH
+- [ ] 201 Created for successful POST
+- [ ] 204 No Content for successful DELETE
+- [ ] 400 Bad Request for invalid data
+- [ ] 401 Unauthorized for missing/invalid auth
+- [ ] 403 Forbidden for insufficient permissions
+- [ ] 404 Not Found for missing resources
+- [ ] 409 Conflict for duplicates
+- [ ] 422 Validation Error for schema failures
+
+## Error Handling
+
+- [ ] Consistent error response format (`error`, `status_code`, `detail`)
+- [ ] Custom exception handlers registered
+- [ ] Validation errors return field-level details
+- [ ] Integrity errors handled gracefully (409 Conflict)
+- [ ] Generic exceptions caught and logged
+
+## Pagination
+
+- [ ] List endpoints support pagination (`skip`, `limit`)
+- [ ] Maximum limit enforced (100 default)
+- [ ] Paginated response includes `total`, `has_more`
+- [ ] Cursor-based pagination for large datasets
+- [ ] Pagination tested with edge cases
+
+## Authentication
+
+- [ ] JWT authentication required on protected endpoints
+- [ ] `tenant_id` extracted from JWT claims
+- [ ] Superuser flag checked for admin endpoints
+- [ ] Public endpoints explicitly marked (no auth)
+- [ ] Authentication tested in integration tests
+
+## OpenAPI Documentation
+
+- [ ] Endpoint docstrings describe purpose
+- [ ] All parameters documented
+- [ ] Response schemas documented
+- [ ] Error responses documented (409, 422, etc.)
+- [ ] Examples provided for complex schemas
+- [ ] Tags assigned for logical grouping
+
+## Rate Limiting
+
+- [ ] Public endpoints have rate limiting
+- [ ] Critical endpoints (create, update) have stricter limits
+- [ ] Rate limit uses Upstash Redis
+- [ ] Rate limit headers included in response
+
+## Testing
+
+- [ ] Unit tests for repository methods
+- [ ] Integration tests for all CRUD operations
+- [ ] Tenant isolation verified in tests
+- [ ] Duplicate detection tested (409 Conflict)
+- [ ] Validation errors tested (422 Unprocessable)
+- [ ] Authentication tested (401 Unauthorized)
+- [ ] Tests run with Doppler (`doppler run --config test`)
+
+## Security
+
+- [ ] No SQL injection vulnerabilities (using ORM)
+- [ ] No hardcoded secrets or credentials
+- [ ] CORS origins from Doppler (not hardcoded)
+- [ ] Input validation on all fields
+- [ ] Output encoding prevents XSS
+- [ ] Rate limiting protects against abuse
+
+## Performance
+
+- [ ] Database queries use indexes
+- [ ] N+1 queries avoided
+- [ ] Pagination prevents loading all records
+- [ ] Heavy operations use background jobs
+- [ ] Caching implemented where appropriate
+
+## Before Merging
+
+- [ ] All tests pass (`pytest`)
+- [ ] Coverage >80% for new code
+- [ ] OpenAPI docs reviewed at `/docs`
+- [ ] Tested locally with Doppler
+- [ ] Code reviewed by teammate
+- [ ] No console.log or debug prints
+- [ ] Migration created if schema changed

skills/api-design-standards/checklists/security-review.md

@@ -0,0 +1,84 @@
+# API Security Review Checklist
+
+**Security-focused review for API endpoints.**
+
+## Authentication & Authorization
+
+- [ ] JWT required on all protected endpoints
+- [ ] Token expiration enforced
+- [ ] Superuser flag checked for admin operations
+- [ ] No authentication bypass vulnerabilities
+- [ ] Session management secure
+
+## Multi-Tenant Security
+
+- [ ] All queries filter by `tenant_id`
+- [ ] No cross-tenant data leaks possible
+- [ ] Repository pattern enforces isolation
+- [ ] Admin endpoints verify superuser
+- [ ] Test cases prove isolation
+
+## Input Validation
+
+- [ ] All inputs validated with Pydantic
+- [ ] SQL injection prevented (using ORM)
+- [ ] XSS prevented (output encoding)
+- [ ] File uploads validated (type, size)
+- [ ] Email format validated
+- [ ] URL format validated
+- [ ] Integer ranges validated
+- [ ] String lengths validated
+
+## Sensitive Data
+
+- [ ] Passwords hashed with bcrypt
+- [ ] Password hashes never returned
+- [ ] Secrets from Doppler (not hardcoded)
+- [ ] PII properly handled
+- [ ] No sensitive data in logs
+- [ ] No sensitive data in error messages
+
+## Rate Limiting
+
+- [ ] Public endpoints rate limited
+- [ ] Login endpoints strictly rate limited
+- [ ] Rate limit uses Redis
+- [ ] Rate limit tested
+
+## CORS
+
+- [ ] Allowed origins from Doppler
+- [ ] No `allow_origins=["*"]` in production
+- [ ] Credentials allowed only for trusted origins
+- [ ] Preflight requests handled
+
+## Error Handling
+
+- [ ] No stack traces in production responses
+- [ ] Generic errors for security issues
+- [ ] Detailed errors only in dev/test
+- [ ] Errors logged server-side
+
+## OWASP Top 10
+
+- [ ] A01: Broken Access Control - ✅ Tenant isolation
+- [ ] A02: Cryptographic Failures - ✅ Bcrypt, Doppler
+- [ ] A03: Injection - ✅ ORM, validation
+- [ ] A04: Insecure Design - ✅ Repository pattern
+- [ ] A05: Security Misconfiguration - ✅ CORS, secrets
+- [ ] A06: Vulnerable Components - ✅ Updated dependencies
+- [ ] A07: Identification Failures - ✅ JWT, rate limiting
+- [ ] A08: Integrity Failures - ✅ Input validation
+- [ ] A09: Logging Failures - ✅ Error logging
+- [ ] A10: SSRF - ✅ URL validation
+
+## Before Production Deploy
+
+- [ ] Security scan passed
+- [ ] No hardcoded secrets
+- [ ] Doppler secrets configured
+- [ ] CORS origins configured
+- [ ] Rate limiting enabled
+- [ ] HTTPS enforced
+- [ ] Error handling tested
+- [ ] Penetration test completed