clinch/docs/beta-checklist.md

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 for detailed vulnerability tracking and fixes. Outstanding Security Issues: 3 (all MEDIUM/LOW priority) - Phases 1-4 complete ✅

---

Security Scanning

Automated Security Tools

• 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

• bundler-audit - Dependency vulnerability scanning

  • Status: ✅ No vulnerabilities found
  • Command: bin/bundler-audit check --update
  • CI: Runs on every PR and push to main

• importmap audit - JavaScript dependency scanning

  • CI: Runs on every PR and push to main

• Test Coverage - SimpleCov integration

  • Command: COVERAGE=1 bin/rails test
  • Coverage report: coverage/index.html

Security Features Implemented

Authentication

• Secure password storage (bcrypt with Rails defaults)
• TOTP 2FA with backup codes
• WebAuthn/Passkey support (FIDO2)
• Session management with device tracking
• Session revocation (individual and bulk)
• Remember me with configurable expiry
• Account invitation flow with expiring tokens
• Password reset with expiring tokens

OIDC Security

• Authorization code flow with PKCE support
• Refresh token rotation
• Token family tracking (detects replay attacks)
• All tokens HMAC-SHA256 hashed in database
• Configurable token expiry (access, refresh, ID)
• One-time use authorization codes
• Pairwise subject identifiers (privacy)
• ID tokens signed with RS256
• Token revocation endpoint (RFC 7009)
• Proper at_hash validation
• OIDC standard claims (auth_time, acr, azp)
• Automatic cleanup of expired tokens

Access Control

• Group-based authorization
• Application-level access control
• Admin vs. regular user roles
• User status management (active, disabled, pending)
• TOTP enforcement per-user
• ForwardAuth policy enforcement

Input Validation

• Strong parameter filtering
• URL validation for redirect URIs and landing URLs
• Email validation and normalization
• Slug validation (alphanumeric + hyphens)
• Domain pattern validation for ForwardAuth
• JSON parsing with error handling
• File upload validation (type, size for app icons)

Output Encoding

• HTML escaping by default (Rails 8)
• JSON encoding for API responses
• JWT encoding for ID tokens
• Proper content types for responses

Session Security

• Secure, httponly cookies
• SameSite cookie attribute
• Session timeout
• IP and User-Agent tracking
• CSRF protection

Cryptography

• SecureRandom for tokens
• bcrypt for passwords
• HMAC-SHA256 for token hashing
• RS256 for JWT signing
• Proper secret management (Rails credentials)

Testing

Test Coverage

• 341 tests across integration, model, controller, service, and system tests
• 1349 assertions
• 0 failures, 0 errors

Test Categories

• Integration tests (invitation flow, forward auth, WebAuthn, session security)
• Model tests (OIDC tokens, users, applications, groups, authorization codes)
• Controller tests (TOTP, sessions, passwords, OIDC flows, input validation)
• Service tests (JWT generation and validation)
• System tests (forward auth, WebAuthn security)

Security-Critical Test Coverage

• OIDC authorization code flow
• PKCE flow
• Refresh token rotation
• Token replay attack detection
• Access control (group-based)
• Input validation
• Session security
• WebAuthn credential handling
• TOTP validation

Code Quality

• RuboCop - Code style and linting

  • Configuration: Rails Omakase
  • CI: Runs on every PR and push to main

• 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
• Ensure OIDC private key generation process is documented

Database

• Migrations are idempotent
• Indexes on foreign keys
• Proper constraints and validations
• 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

• Docker support
• 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

• No secrets in code
• Rails credentials for sensitive data
• Document secret rotation process
• Document OIDC key rotation process

Logging & Monitoring

• 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

• 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):

• All automated security scans passing
• All tests passing
• Core features implemented and tested
• 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