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

• Trivy - Container image vulnerability scanning

  • Scans Docker images for OS and system package vulnerabilities
  • CI: Builds and scans image on every PR and push to main
  • Results uploaded to GitHub Security tab

• Dependabot - Automated dependency updates

  • Creates PRs for outdated dependencies
  • Enabled for Ruby gems and GitHub Actions

• GitHub Secret Scanning - Detects leaked credentials

  • Push protection enabled to block commits with secrets

• 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 and authorization codes HMAC-SHA256 hashed in database
• TOTP secrets AES-256-GCM encrypted at rest (Rails credentials)
• 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

• StandardRB - Code style and linting

  • 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 (Docker Compose with .env configuration, upgrading, logs)
• Backup and restore documentation

Security Hardening

Headers & CSP

• Content Security Policy (comprehensive policy in config/initializers/content_security_policy.rb)
• X-Frame-Options (DENY in production config)
• X-Content-Type-Options (nosniff - Rails default)
• Referrer-Policy (strict-origin-when-cross-origin in production config)

Rate Limiting

• Login attempt rate limiting (20/3min on sessions#create)
• TOTP verification rate limiting (10/3min on sessions#verify_totp)
• WebAuthn rate limiting (10/1min on webauthn endpoints, 10/3min on session endpoints)
• Password reset rate limiting (10/3min on request, 10/10min on completion)
• Invitation acceptance rate limiting (10/10min)
• OAuth token endpoint rate limiting (60/1min on token, 30/1min on authorize)
• Backup code rate limiting (5 failed attempts per hour, model-level)

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)
• Parameter filtering configured (passwords, tokens, secrets, backup codes, emails filtered from logs)
• 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 (Post-Beta)

• Rate limiting on authentication endpoints (comprehensive coverage implemented)
• Account lockout after N failed attempts (rate limiting provides similar protection)
• Admin audit logging
• Security event notifications (email/webhook alerts for suspicious activity)
• Advanced brute force detection (pattern analysis beyond rate limiting)
• Suspicious login detection (geolocation, device fingerprinting)
• IP allowlist/blocklist

Protocol Conformance & Security Review

Protocol Conformance (Completed):

• OpenID Connect Conformance Testing - 48/48 tests passed
  • OIDC authorization code flow ✅
  • PKCE flow ✅
  • Token security (ID tokens, access tokens, refresh tokens) ✅
  • Scope-based claim filtering ✅
  • Standard OIDC claims and metadata ✅
  • Proper OAuth2 error handling (redirect vs. error page) ✅

External Security Review (Optional for Post-Beta):

• Traditional security audit or penetration test
  • Note: OIDC conformance tests protocol compliance, not security vulnerabilities
  • A dedicated security audit would test for injection, XSS, auth bypasses, etc.
• Bug bounty program
• WebAuthn implementation 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
• Backup/restore documentation
• Production deployment guide
• Protocol conformance validation
  • OpenID Connect Conformance Testing - 48 tests PASSED, 0 failures, 0 warnings

Important (Should have for Beta):

• Rate limiting on auth endpoints
• Security headers configuration documented (CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy)
• Known limitations documented (ForwardAuth same-domain requirement in README)
• Admin audit logging

Nice to have (Can defer to post-Beta):

• Bug bounty program
• Advanced monitoring/alerting
• Automated security testing in CI beyond brakeman/bundler-audit
  • Dependabot (automated dependency updates)
  • GitHub Secret Scanning (automatic with push protection enabled)
  • Container image scanning (Trivy scans Docker images for OS/system vulnerabilities)
  • DAST/Dynamic testing (OWASP ZAP) - optional for post-Beta

Status Summary

Current Status: Ready for Beta Release 🎉

Strengths:

• ✅ Comprehensive security tooling in place
• ✅ Strong test coverage (374 tests, 1538 assertions)
• ✅ Modern security features (PKCE, token rotation, WebAuthn)
• ✅ Clean security scans (brakeman, bundler-audit, Trivy)
• ✅ Well-documented codebase
• ✅ OpenID Connect Conformance certified - 48/48 tests passed

All Critical Requirements Met:

• All automated security scans passing ✅
• All tests passing (374 tests, 1542 assertions) ✅
• Core features implemented and tested ✅
• Documentation complete ✅
• Production deployment guide ✅
• Protocol conformance validation complete ✅

Optional for Post-Beta:

• Admin audit logging
• Traditional security audit/penetration test
• Bug bounty program
• Advanced monitoring/alerting

Recommendation: Clinch meets all critical requirements for Beta release. The OIDC implementation is protocol-compliant (48/48 conformance tests passed), security scans are clean, and the codebase has strong test coverage.

For production use in security-sensitive environments, consider a traditional security audit or penetration test post-Beta to validate against common vulnerabilities (injection, XSS, auth bypasses, etc.) beyond protocol conformance.

---

Last updated: 2026-01-02