dkam/clinch
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases Wiki Activity

Development Progress Tracker - Built vs. Remaining Features #1

New Issue
Open
opened 2025-10-23 06:47:25 +00:00 by Claude · 0 comments
Claude commented 2025-10-23 06:47:25 +00:00
Copy Link
Copy Source

Clinch Development Progress

This issue tracks what has been built and what remains to be implemented for Clinch, a lightweight self-hosted SSO portal for home labs.

✅ Completed Features

Core Infrastructure

  • Rails 8.1 application setup
  • Multi-database SQLite configuration (primary, cache, queue, cable)
  • Solid Cache, Queue, and Cable configured for development and production
  • Request ID logging in development
  • Proper .gitignore with .env protection
  • Environment variable template (.env.example)

Authentication & User Management

  • Rails 8 authentication generator integration
  • User model with secure password (bcrypt)
  • TOTP methods in User model (enable, verify, backup codes generation)
  • Session model with device tracking (device name, IP, last activity)
  • Remember me functionality
  • Session expiry logic
  • First-run setup (first user automatically becomes admin)
  • Signup page (only accessible when no users exist)
  • Sign in page with status checking
  • Token generation using generates_token_for (invitation, password reset, magic login)

Data Models

  • User model with admin, TOTP, and status fields
  • Session model with device tracking
  • Group model (flat structure, no hierarchies)
  • UserGroup join table
  • Application model (OIDC credentials, app types)
  • ApplicationGroup join table
  • OidcAuthorizationCode model
  • OidcAccessToken model

UI & Navigation

  • Sidebar-only navigation with Clinch branding
  • User email and admin badge in sidebar
  • Conditional layout (authenticated vs. public)
  • Mobile menu button
  • Flash message partial
  • Dashboard with user welcome and session stats
  • Admin quick actions on dashboard
  • Profile page with multiple sections

Profile Management

  • Email address update form
  • Password change form (basic - needs current password requirement)
  • TOTP section with placeholder buttons
  • Active sessions list with device info
  • Session revocation (revoke other sessions)
  • Protection against revoking current session

OpenID Connect (OIDC) Provider

  • Discovery Endpoint
    • /.well-known/openid-configuration with provider metadata
  • JWKS Endpoint
    • /.well-known/jwks.json - Public keys for JWT verification
  • Authorization Endpoint
    • /oauth/authorize - OAuth 2.0 authorization request
    • User consent page
    • Authorization code generation
    • Group-based access control
  • Token Endpoint
    • /oauth/token - Exchange authorization code for access/ID tokens
    • JWT signing for ID tokens (RS256)
    • Client authentication (Basic and POST)
  • UserInfo Endpoint
    • /oauth/userinfo - Return user claims
    • Support standard OIDC claims (sub, email, name, groups, admin)

Trusted-Header SSO (ForwardAuth)

  • Verification Endpoint
    • /api/verify - Validate session and return user info
    • Return 200 with headers for authenticated users
    • Return 401/403 for unauthenticated/unauthorized users
    • Support group-based access control
    • Header injection (Remote-User, Remote-Email, Remote-Groups, Remote-Admin)
    • Session validation and expiry checking
    • Application slug support (query param or X-Forwarded-Host)

Routes

  • Authentication routes (/signup, /signin, /signout)
  • Dashboard route (/)
  • Profile routes
  • Session management routes
  • OIDC routes (discovery, jwks, authorize, token, userinfo)
  • ForwardAuth routes (/api/verify)
  • Admin namespace routes (placeholder)

⏳ Remaining Features

Security Enhancements

  • Require current password for password changes (discussed, not implemented)
  • Password/TOTP requirements for:
    • Disabling 2FA
    • Viewing backup codes
    • Possibly changing email (to be decided)

TOTP Two-Factor Authentication

  • TOTP Enable Flow
    • TotpController (or extend ProfilesController)
    • QR code setup page with provisioning URI
    • TOTP verification during setup
    • One-time backup codes display
    • Backup codes download/print functionality
  • TOTP Disable Flow
    • Password verification before disabling
    • Confirmation modal/form
  • TOTP Login Flow
    • TOTP verification page during login
    • Redirect from SessionsController to TOTP verification
    • Backup code entry support
    • Rate limiting for failed attempts

Admin Interface

  • Admin::DashboardController
    • Quick actions for common tasks
    • Recent activity feed
    • System statistics
  • Admin::UsersController
    • List all users
    • Create/invite users
    • Edit user details
    • Activate/deactivate users
    • Promote/demote admin status
    • Force password reset
  • Admin::ApplicationsController
    • List all registered applications
    • Register new application
    • Edit application details
    • Configure allowed groups
    • Regenerate client credentials (OIDC)
    • Activate/deactivate applications
  • Admin::GroupsController
    • List all groups
    • Create new group
    • Edit group details
    • Manage group members
    • Delete groups

Future Enhancements

  • SAML Provider (planned for future)
  • Audit logging (track security events)
  • Email notifications (password resets, new device logins)
  • Rate limiting (prevent brute force attacks)
  • API tokens (for programmatic access)

Technical Stack

  • Framework: Rails 8.1
  • Database: SQLite (primary, cache, queue, cable)
  • Background Jobs: Solid Queue
  • Caching: Solid Cache
  • WebSockets: Solid Cable
  • Authentication: bcrypt, Rails 8 authentication generator
  • 2FA: rotp, rqrcode
  • OIDC: JWT (RS256), OAuth 2.0 authorization code flow
  • Styling: Tailwind CSS
  • Token Generation: generates_token_for (Rails 8)

Next Immediate Steps

Based on current discussion:

  1. ✨ Build Admin::UsersController (basic CRUD for user management)
  2. ✨ Build Admin::ApplicationsController (manage OIDC/ForwardAuth apps)
  3. ✨ Build Admin::GroupsController (manage groups and memberships)
  4. ✨ Improve TOTP UX (backup code download/print, better confirmation flows)

This issue will be updated as features are completed. Feel free to reference specific sections when creating focused feature issues.

## Clinch Development Progress This issue tracks what has been built and what remains to be implemented for Clinch, a lightweight self-hosted SSO portal for home labs. --- ## ✅ Completed Features ### Core Infrastructure - [x] Rails 8.1 application setup - [x] Multi-database SQLite configuration (primary, cache, queue, cable) - [x] Solid Cache, Queue, and Cable configured for development and production - [x] Request ID logging in development - [x] Proper .gitignore with .env protection - [x] Environment variable template (.env.example) ### Authentication & User Management - [x] Rails 8 authentication generator integration - [x] User model with secure password (bcrypt) - [x] TOTP methods in User model (enable, verify, backup codes generation) - [x] Session model with device tracking (device name, IP, last activity) - [x] Remember me functionality - [x] Session expiry logic - [x] First-run setup (first user automatically becomes admin) - [x] Signup page (only accessible when no users exist) - [x] Sign in page with status checking - [x] Token generation using `generates_token_for` (invitation, password reset, magic login) ### Data Models - [x] User model with admin, TOTP, and status fields - [x] Session model with device tracking - [x] Group model (flat structure, no hierarchies) - [x] UserGroup join table - [x] Application model (OIDC credentials, app types) - [x] ApplicationGroup join table - [x] OidcAuthorizationCode model - [x] OidcAccessToken model ### UI & Navigation - [x] Sidebar-only navigation with Clinch branding - [x] User email and admin badge in sidebar - [x] Conditional layout (authenticated vs. public) - [x] Mobile menu button - [x] Flash message partial - [x] Dashboard with user welcome and session stats - [x] Admin quick actions on dashboard - [x] Profile page with multiple sections ### Profile Management - [x] Email address update form - [x] Password change form (basic - needs current password requirement) - [x] TOTP section with placeholder buttons - [x] Active sessions list with device info - [x] Session revocation (revoke other sessions) - [x] Protection against revoking current session ### OpenID Connect (OIDC) Provider - [x] **Discovery Endpoint** - [x] `/.well-known/openid-configuration` with provider metadata - [x] **JWKS Endpoint** - [x] `/.well-known/jwks.json` - Public keys for JWT verification - [x] **Authorization Endpoint** - [x] `/oauth/authorize` - OAuth 2.0 authorization request - [x] User consent page - [x] Authorization code generation - [x] Group-based access control - [x] **Token Endpoint** - [x] `/oauth/token` - Exchange authorization code for access/ID tokens - [x] JWT signing for ID tokens (RS256) - [x] Client authentication (Basic and POST) - [x] **UserInfo Endpoint** - [x] `/oauth/userinfo` - Return user claims - [x] Support standard OIDC claims (sub, email, name, groups, admin) ### Trusted-Header SSO (ForwardAuth) - [x] **Verification Endpoint** - [x] `/api/verify` - Validate session and return user info - [x] Return 200 with headers for authenticated users - [x] Return 401/403 for unauthenticated/unauthorized users - [x] Support group-based access control - [x] Header injection (Remote-User, Remote-Email, Remote-Groups, Remote-Admin) - [x] Session validation and expiry checking - [x] Application slug support (query param or X-Forwarded-Host) ### Routes - [x] Authentication routes (/signup, /signin, /signout) - [x] Dashboard route (/) - [x] Profile routes - [x] Session management routes - [x] OIDC routes (discovery, jwks, authorize, token, userinfo) - [x] ForwardAuth routes (/api/verify) - [x] Admin namespace routes (placeholder) --- ## ⏳ Remaining Features ### Security Enhancements - [x] **Require current password for password changes** (discussed, not implemented) - [x] Password/TOTP requirements for: - [x] Disabling 2FA - [x] Viewing backup codes - [ ] Possibly changing email (to be decided) ### TOTP Two-Factor Authentication - [x] **TOTP Enable Flow** - [x] TotpController (or extend ProfilesController) - [x] QR code setup page with provisioning URI - [x] TOTP verification during setup - [x] One-time backup codes display - [x] Backup codes download/print functionality - [x] **TOTP Disable Flow** - [x] Password verification before disabling - [x] Confirmation modal/form - [x] **TOTP Login Flow** - [x] TOTP verification page during login - [x] Redirect from SessionsController to TOTP verification - [x] Backup code entry support - [x] Rate limiting for failed attempts ### Admin Interface - [x] **Admin::DashboardController** - [x] Quick actions for common tasks - [x] Recent activity feed - [x] System statistics - [x] **Admin::UsersController** - [x] List all users - [x] Create/invite users - [x] Edit user details - [x] Activate/deactivate users - [x] Promote/demote admin status - [ ] Force password reset - [ ] **Admin::ApplicationsController** - [ ] List all registered applications - [ ] Register new application - [ ] Edit application details - [ ] Configure allowed groups - [ ] Regenerate client credentials (OIDC) - [ ] Activate/deactivate applications - [ ] **Admin::GroupsController** - [ ] List all groups - [ ] Create new group - [ ] Edit group details - [ ] Manage group members - [ ] Delete groups ### Future Enhancements - [ ] **SAML Provider** (planned for future) - [ ] **Audit logging** (track security events) - [ ] **Email notifications** (password resets, new device logins) - [ ] **Rate limiting** (prevent brute force attacks) - [ ] **API tokens** (for programmatic access) --- ## Technical Stack - **Framework**: Rails 8.1 - **Database**: SQLite (primary, cache, queue, cable) - **Background Jobs**: Solid Queue - **Caching**: Solid Cache - **WebSockets**: Solid Cable - **Authentication**: bcrypt, Rails 8 authentication generator - **2FA**: rotp, rqrcode - **OIDC**: JWT (RS256), OAuth 2.0 authorization code flow - **Styling**: Tailwind CSS - **Token Generation**: generates_token_for (Rails 8) --- ## Next Immediate Steps Based on current discussion: 1. ✨ **Build Admin::UsersController** (basic CRUD for user management) 2. ✨ **Build Admin::ApplicationsController** (manage OIDC/ForwardAuth apps) 3. ✨ **Build Admin::GroupsController** (manage groups and memberships) 4. ✨ **Improve TOTP UX** (backup code download/print, better confirmation flows) --- This issue will be updated as features are completed. Feel free to reference specific sections when creating focused feature issues.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
dkam (Dan Milne)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: dkam/clinch#1