269 lines
8.1 KiB
Markdown
269 lines
8.1 KiB
Markdown
# Beta Release Readiness Checklist
|
|
|
|
This checklist ensures Clinch meets security, quality, and documentation standards before moving from "experimental" to "Beta" status.
|
|
|
|
> **Security Implementation Status:** See [security-todo.md](security-todo.md) for detailed vulnerability tracking and fixes.
|
|
> **Outstanding Security Issues:** 3 (all MEDIUM/LOW priority) - Phases 1-4 complete ✅
|
|
|
|
---
|
|
|
|
## Security Scanning
|
|
|
|
### Automated Security Tools
|
|
- [x] **Brakeman** - Static security analysis for Rails
|
|
- Status: ✅ Passing (2 weak warnings documented and accepted)
|
|
- Command: `bin/brakeman --no-pager`
|
|
- CI: Runs on every PR and push to main
|
|
- Warnings documented in `config/brakeman.ignore`
|
|
|
|
- [x] **bundler-audit** - Dependency vulnerability scanning
|
|
- Status: ✅ No vulnerabilities found
|
|
- Command: `bin/bundler-audit check --update`
|
|
- CI: Runs on every PR and push to main
|
|
|
|
- [x] **importmap audit** - JavaScript dependency scanning
|
|
- CI: Runs on every PR and push to main
|
|
|
|
- [x] **Test Coverage** - SimpleCov integration
|
|
- Command: `COVERAGE=1 bin/rails test`
|
|
- Coverage report: `coverage/index.html`
|
|
|
|
### Security Features Implemented
|
|
|
|
#### Authentication
|
|
- [x] Secure password storage (bcrypt with Rails defaults)
|
|
- [x] TOTP 2FA with backup codes
|
|
- [x] WebAuthn/Passkey support (FIDO2)
|
|
- [x] Session management with device tracking
|
|
- [x] Session revocation (individual and bulk)
|
|
- [x] Remember me with configurable expiry
|
|
- [x] Account invitation flow with expiring tokens
|
|
- [x] Password reset with expiring tokens
|
|
|
|
#### OIDC Security
|
|
- [x] Authorization code flow with PKCE support
|
|
- [x] Refresh token rotation
|
|
- [x] Token family tracking (detects replay attacks)
|
|
- [x] All tokens HMAC-SHA256 hashed in database
|
|
- [x] Configurable token expiry (access, refresh, ID)
|
|
- [x] One-time use authorization codes
|
|
- [x] Pairwise subject identifiers (privacy)
|
|
- [x] ID tokens signed with RS256
|
|
- [x] Token revocation endpoint (RFC 7009)
|
|
- [x] Proper `at_hash` validation
|
|
- [x] OIDC standard claims (auth_time, acr, azp)
|
|
- [x] Automatic cleanup of expired tokens
|
|
|
|
#### Access Control
|
|
- [x] Group-based authorization
|
|
- [x] Application-level access control
|
|
- [x] Admin vs. regular user roles
|
|
- [x] User status management (active, disabled, pending)
|
|
- [x] TOTP enforcement per-user
|
|
- [x] ForwardAuth policy enforcement
|
|
|
|
#### Input Validation
|
|
- [x] Strong parameter filtering
|
|
- [x] URL validation for redirect URIs and landing URLs
|
|
- [x] Email validation and normalization
|
|
- [x] Slug validation (alphanumeric + hyphens)
|
|
- [x] Domain pattern validation for ForwardAuth
|
|
- [x] JSON parsing with error handling
|
|
- [x] File upload validation (type, size for app icons)
|
|
|
|
#### Output Encoding
|
|
- [x] HTML escaping by default (Rails 8)
|
|
- [x] JSON encoding for API responses
|
|
- [x] JWT encoding for ID tokens
|
|
- [x] Proper content types for responses
|
|
|
|
#### Session Security
|
|
- [x] Secure, httponly cookies
|
|
- [x] SameSite cookie attribute
|
|
- [x] Session timeout
|
|
- [x] IP and User-Agent tracking
|
|
- [x] CSRF protection
|
|
|
|
#### Cryptography
|
|
- [x] SecureRandom for tokens
|
|
- [x] bcrypt for passwords
|
|
- [x] HMAC-SHA256 for token hashing
|
|
- [x] RS256 for JWT signing
|
|
- [x] Proper secret management (Rails credentials)
|
|
|
|
## Testing
|
|
|
|
### Test Coverage
|
|
- [x] **341 tests** across integration, model, controller, service, and system tests
|
|
- [x] **1349 assertions**
|
|
- [x] **0 failures, 0 errors**
|
|
|
|
### Test Categories
|
|
- [x] Integration tests (invitation flow, forward auth, WebAuthn, session security)
|
|
- [x] Model tests (OIDC tokens, users, applications, groups, authorization codes)
|
|
- [x] Controller tests (TOTP, sessions, passwords, OIDC flows, input validation)
|
|
- [x] Service tests (JWT generation and validation)
|
|
- [x] System tests (forward auth, WebAuthn security)
|
|
|
|
### Security-Critical Test Coverage
|
|
- [x] OIDC authorization code flow
|
|
- [x] PKCE flow
|
|
- [x] Refresh token rotation
|
|
- [x] Token replay attack detection
|
|
- [x] Access control (group-based)
|
|
- [x] Input validation
|
|
- [x] Session security
|
|
- [x] WebAuthn credential handling
|
|
- [x] TOTP validation
|
|
|
|
## Code Quality
|
|
|
|
- [x] **RuboCop** - Code style and linting
|
|
- Configuration: Rails Omakase
|
|
- CI: Runs on every PR and push to main
|
|
|
|
- [x] **Documentation** - Comprehensive README
|
|
- Feature documentation
|
|
- Setup instructions
|
|
- Configuration guide
|
|
- Rails console guide
|
|
- API/protocol documentation
|
|
|
|
## Production Readiness
|
|
|
|
### Configuration
|
|
- [ ] Review all environment variables
|
|
- [ ] Document required vs. optional configuration
|
|
- [ ] Provide sensible defaults
|
|
- [ ] Validate production SMTP configuration
|
|
- [x] Ensure OIDC private key generation process is documented
|
|
|
|
### Database
|
|
- [x] Migrations are idempotent
|
|
- [x] Indexes on foreign keys
|
|
- [x] Proper constraints and validations
|
|
- [x] SQLite production-ready (Rails 8)
|
|
|
|
### Performance
|
|
- [ ] Review N+1 queries
|
|
- [ ] Add database indexes where needed
|
|
- [ ] Test with realistic data volumes
|
|
- [ ] Review token cleanup job performance
|
|
|
|
### Deployment
|
|
- [x] Docker support
|
|
- [x] Docker Compose example
|
|
- [ ] Production deployment guide
|
|
- [ ] Backup and restore documentation
|
|
- [ ] Migration strategy documentation
|
|
|
|
## Security Hardening
|
|
|
|
### Headers & CSP
|
|
- [ ] Review Content Security Policy
|
|
- [ ] HSTS configuration
|
|
- [ ] X-Frame-Options
|
|
- [ ] X-Content-Type-Options
|
|
- [ ] Referrer-Policy
|
|
|
|
### Rate Limiting
|
|
- [ ] Login attempt rate limiting
|
|
- [ ] API endpoint rate limiting
|
|
- [ ] Token endpoint rate limiting
|
|
- [ ] Password reset rate limiting
|
|
|
|
### Secrets Management
|
|
- [x] No secrets in code
|
|
- [x] Rails credentials for sensitive data
|
|
- [ ] Document secret rotation process
|
|
- [ ] Document OIDC key rotation process
|
|
|
|
### Logging & Monitoring
|
|
- [x] Sentry integration (optional)
|
|
- [ ] Document what should be logged
|
|
- [ ] Document what should NOT be logged (tokens, passwords)
|
|
- [ ] Audit log for admin actions
|
|
|
|
## Known Limitations & Risks
|
|
|
|
### Documented Risks
|
|
- [x] Document that ForwardAuth requires same-domain setup
|
|
- [ ] Document HTTPS requirement for production
|
|
- [ ] Document backup code security (single-use, store securely)
|
|
- [ ] Document admin password security requirements
|
|
|
|
### Future Security Enhancements
|
|
- [ ] Rate limiting on authentication endpoints
|
|
- [ ] Account lockout after N failed attempts
|
|
- [ ] Admin audit logging
|
|
- [ ] Security event notifications
|
|
- [ ] Brute force detection
|
|
- [ ] Suspicious login detection
|
|
- [ ] IP allowlist/blocklist
|
|
|
|
## External Security Review
|
|
|
|
- [ ] Consider bug bounty or security audit
|
|
- [ ] Penetration testing for OIDC flows
|
|
- [ ] WebAuthn implementation review
|
|
- [ ] Token security review
|
|
|
|
## Documentation for Users
|
|
|
|
- [ ] Security best practices guide
|
|
- [ ] Incident response guide
|
|
- [ ] Backup and disaster recovery guide
|
|
- [ ] Upgrade guide
|
|
- [ ] Breaking change policy
|
|
|
|
## Beta Release Criteria
|
|
|
|
To move from "experimental" to "Beta", the following must be completed:
|
|
|
|
**Critical (Required for Beta):**
|
|
- [x] All automated security scans passing
|
|
- [x] All tests passing
|
|
- [x] Core features implemented and tested
|
|
- [x] Basic documentation complete
|
|
- [ ] At least one external security review or penetration test
|
|
- [ ] Production deployment guide
|
|
- [ ] Backup/restore documentation
|
|
|
|
**Important (Should have for Beta):**
|
|
- [ ] Rate limiting on auth endpoints
|
|
- [ ] Security headers configuration documented
|
|
- [ ] Admin audit logging
|
|
- [ ] Known limitations documented
|
|
|
|
**Nice to have (Can defer to post-Beta):**
|
|
- [ ] Bug bounty program
|
|
- [ ] Advanced monitoring/alerting
|
|
- [ ] Automated security testing in CI beyond brakeman/bundler-audit
|
|
|
|
## Status Summary
|
|
|
|
**Current Status:** Pre-Beta / Experimental
|
|
|
|
**Strengths:**
|
|
- ✅ Comprehensive security tooling in place
|
|
- ✅ Strong test coverage (341 tests, 1349 assertions)
|
|
- ✅ Modern security features (PKCE, token rotation, WebAuthn)
|
|
- ✅ Clean security scans (brakeman, bundler-audit)
|
|
- ✅ Well-documented codebase
|
|
|
|
**Before Beta Release:**
|
|
- 🔶 External security review recommended
|
|
- 🔶 Rate limiting implementation needed
|
|
- 🔶 Production deployment documentation
|
|
- 🔶 Security hardening checklist completion
|
|
|
|
**Recommendation:** Consider Beta status after:
|
|
1. External security review or penetration testing
|
|
2. Rate limiting implementation
|
|
3. Production hardening documentation
|
|
4. 1-2 months of real-world testing
|
|
|
|
---
|
|
|
|
Last updated: 2026-01-01
|