Update docs. Implemented a one-time token to work around domain cookies not being immediately return by the browser. Reduce db queries on /api/verify requests.

app/controllers/api/forward_auth_controller.rb

@@ -10,15 +10,19 @@ module Api
     def verify
       # Note: app_slug parameter is no longer used - we match domains directly with ForwardAuthRule
 
-      # Get the session from cookie
-      session_id = extract_session_id
+      # Check for one-time forward auth token first (to handle race condition)
+      session_id = check_forward_auth_token
+
+      # If no token found, try to get session from cookie
+      session_id ||= extract_session_id
+
       unless session_id
-        # No session cookie - user is not authenticated
+        # No session cookie or token - user is not authenticated
         return render_unauthorized("No session cookie")
       end
 
-      # Find the session
-      session = Session.find_by(id: session_id)
+      # Find the session with user association (eager loading for performance)
+      session = Session.includes(:user).find_by(id: session_id)
       unless session
         # Invalid session
         return render_unauthorized("Invalid session")
@@ -30,10 +34,10 @@ module Api
         return render_unauthorized("Session expired")
       end
 
-      # Update last activity
+      # Update last activity (skip validations for performance)
       session.update_column(:last_activity_at, Time.current)
 
-      # Get the user
+      # Get the user (already loaded via includes(:user))
       user = session.user
       unless user.active?
         return render_unauthorized("User account is not active")
@@ -44,8 +48,12 @@ module Api
       forwarded_host = request.headers["X-Forwarded-Host"] || request.headers["Host"]
 
       if forwarded_host.present?
+        # Load active rules with their associations for better performance
+        # Preload groups to avoid N+1 queries in user_allowed? checks
+        rules = ForwardAuthRule.includes(:groups).active
+
         # Find matching forward auth rule for this domain
-        rule = ForwardAuthRule.active.find { |r| r.matches_domain?(forwarded_host) }
+        rule = rules.find { |r| r.matches_domain?(forwarded_host) }
 
         unless rule
           Rails.logger.warn "ForwardAuth: No rule found for domain: #{forwarded_host}"
@@ -91,10 +99,30 @@ module Api
 
     private
 
+    def check_forward_auth_token
+      # Check for one-time token in query parameters (for race condition handling)
+      token = params[:fa_token]
+      return nil unless token.present?
+
+      # Try to get session ID from cache
+      session_id = Rails.cache.read("forward_auth_token:#{token}")
+      return nil unless session_id
+
+      # Verify the session exists and is valid
+      session = Session.find_by(id: session_id)
+      return nil unless session && !session.expired?
+
+      # Delete the token immediately (one-time use)
+      Rails.cache.delete("forward_auth_token:#{token}")
+
+            session_id
+    end
+
     def extract_session_id
       # Extract session ID from cookie
       # Rails uses signed cookies by default
-      cookies.signed[:session_id]
+      session_id = cookies.signed[:session_id]
+            session_id
     end
 
     def extract_app_from_headers

app/controllers/concerns/authentication.rb

@@ -1,3 +1,5 @@
+require 'uri'
+
 module Authentication
   extend ActiveSupport::Concern
 
@@ -35,7 +37,9 @@ module Authentication
     end
 
     def after_authentication_url
-      session.delete(:return_to_after_authenticating) || root_url
+      return_url = session[:return_to_after_authenticating]
+      final_url = session.delete(:return_to_after_authenticating) || root_url
+      final_url
     end
 
     def start_new_session_for(user)
@@ -57,6 +61,10 @@ module Authentication
         cookie_options[:domain] = domain if domain.present?
 
                 cookies.signed.permanent[:session_id] = cookie_options
+
+        # Create a one-time token for immediate forward auth after authentication
+        # This solves the race condition where browser hasn't processed cookie yet
+        create_forward_auth_token(session)
       end
     end
 
@@ -97,4 +105,35 @@ module Authentication
       root_parts = parts[-2..-1]
       ".#{root_parts.join('.')}"
     end
+
+    # Create a one-time token for forward auth to handle the race condition
+    # where the browser hasn't processed the session cookie yet
+    def create_forward_auth_token(session_obj)
+      # Generate a secure random token
+      token = SecureRandom.urlsafe_base64(32)
+
+      # Store it with an expiry of 30 seconds
+      Rails.cache.write(
+        "forward_auth_token:#{token}",
+        session_obj.id,
+        expires_in: 30.seconds
+      )
+
+      # Set the token as a query parameter on the redirect URL
+      # We need to store this in the controller's session
+      controller_session = session
+      if controller_session[:return_to_after_authenticating].present?
+        original_url = controller_session[:return_to_after_authenticating]
+        uri = URI.parse(original_url)
+
+        # Add token as query parameter
+        query_params = URI.decode_www_form(uri.query || "").to_h
+        query_params['fa_token'] = token
+        uri.query = URI.encode_www_form(query_params)
+
+        # Update the session with the tokenized URL
+        controller_session[:return_to_after_authenticating] = uri.to_s
+
+              end
+    end
 end

app/controllers/sessions_controller.rb

@@ -67,6 +67,12 @@ class SessionsController < ApplicationController
     if request.post?
       code = params[:code]&.strip
 
+      # Check if user is already authenticated (prevent duplicate submissions)
+      if authenticated?
+        redirect_to root_path, notice: "Already signed in."
+        return
+      end
+
       # Try TOTP verification first
       if user.verify_totp(code)
         session.delete(:pending_totp_user_id)

app/views/sessions/verify_totp.html.erb

@@ -7,7 +7,10 @@
       </p>
     </div>
 
-    <%= form_with url: totp_verification_path, method: :post, class: "space-y-6" do |form| %>
+    <%= form_with url: totp_verification_path, method: :post, class: "space-y-6", data: {
+      controller: "form-submit-protection",
+      turbo: false
+    } do |form| %>
     <%= hidden_field_tag :rd, params[:rd] if params[:rd].present? %>
       <div>
         <%= label_tag :code, "Verification Code", class: "block text-sm font-medium text-gray-700" %>
@@ -26,6 +29,7 @@
 
       <div>
         <%= form.submit "Verify",
+            data: { form_submit_protection_target: "submit" },
             class: "w-full flex justify-center py-2 px-4 border border-transparent rounded-md shadow-sm text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500" %>
       </div>
     <% end %>

config/puma.rb

@@ -31,6 +31,7 @@ threads threads_count, threads_count
 # Specifies the `port` that Puma will listen on to receive requests; default is 3000.
 port ENV.fetch("PORT", 3000)
 
+
 # Allow puma to be restarted by `bin/rails restart` command.
 plugin :tmp_restart
 

docs/forward-auth.md

@@ -1,9 +1,5 @@
 # Forward Authentication
 
-References:
-- https://www.reddit.com/r/selfhosted/comments/1hybe81/i_wanted_to_implement_my_own_forward_auth_proxy/
-- https://www.kevinsimper.dk/posts/implementing-a-forward_auth-proxy-tips-and-details
-
 ## Overview
 
 Forward authentication allows a reverse proxy (like Caddy, Nginx, Traefik) to delegate authentication decisions to a separate service. Clinch implements this pattern to provide SSO for multiple applications.
@@ -22,7 +18,7 @@ login_params = {
 login_url = "#{base_url}/signin?#{login_params.to_query}"
 ```
 
-Example: `https://clinch.aapamilne.com/signin?rd=https://metube.aapamilne.com/&rm=GET`
+Example: `https://clinch.example.com/signin?rd=https://metube.example.com/&rm=GET`
 
 ### Tip 2: Root Domain Cookies ✅
 
@@ -30,7 +26,7 @@ Clinch sets authentication cookies on the root domain to enable cross-subdomain
 
 ```ruby
 def extract_root_domain(host)
-  # clinch.aapamilne.com -> .aapamilne.com
+  # clinch.example.com -> .example.com
   # app.example.co.uk -> .example.co.uk
   # localhost -> nil (no domain restriction)
 end
@@ -40,14 +36,73 @@ cookies.signed.permanent[:session_id] = {
   httponly: true,
   same_site: :lax,
   secure: Rails.env.production?,
-  domain: ".aapamilne.com"  # Available to all subdomains
+  domain: ".example.com"  # Available to all subdomains
 }
 ```
 
 This allows the same session cookie to work across:
-- `clinch.aapamilne.com` (auth service)
-- `metube.aapamilne.com` (protected app)
-- `sonarr.aapamilne.com` (protected app)
+- `clinch.example.com` (auth service)
+- `metube.example.com` (protected app)
+- `sonarr.example.com` (protected app)
+
+### Tip 3: Race Condition Solution with One-Time Tokens ✅
+
+**Problem**: After successful authentication, there's a race condition where the browser immediately follows the redirect to the protected application, but the reverse proxy makes a forward auth request before the browser has processed and started sending the new session cookie.
+
+**Solution**: Clinch uses a one-time token system to bridge this timing gap:
+
+```ruby
+# During authentication (authentication.rb)
+def create_forward_auth_token(session_obj)
+  token = SecureRandom.urlsafe_base64(32)
+
+  # Store token for 30 seconds
+  Rails.cache.write("forward_auth_token:#{token}", session_obj.id, expires_in: 30.seconds)
+
+  # Add token to redirect URL
+  if session[:return_to_after_authenticating].present?
+    original_url = session[:return_to_after_authenticating]
+    uri = URI.parse(original_url)
+    query_params = URI.decode_www_form(uri.query || "").to_h
+    query_params['fa_token'] = token
+    uri.query = URI.encode_www_form(query_params)
+    session[:return_to_after_authenticating] = uri.to_s
+  end
+end
+```
+
+```ruby
+# In forward auth verification (forward_auth_controller.rb)
+def check_forward_auth_token
+  token = params[:fa_token]
+  return nil unless token.present?
+
+  session_id = Rails.cache.read("forward_auth_token:#{token}")
+  return nil unless session_id
+
+  session = Session.find_by(id: session_id)
+  return nil unless session && !session.expired?
+
+  # Delete token immediately (one-time use)
+  Rails.cache.delete("forward_auth_token:#{token}")
+
+  Rails.logger.info "ForwardAuth: Valid one-time token used for session #{session_id}"
+  session_id
+end
+```
+
+**How it works:**
+1. User authenticates → Rails sets session cookie + generates one-time token
+2. Token gets appended to redirect URL: `https://metube.example.com/?fa_token=abc123...`
+3. Browser follows redirect → Caddy makes forward auth request with token
+4. Forward auth validates token → authenticates user immediately
+5. Token is deleted (one-time use) → subsequent requests use normal cookies
+
+**Security Features:**
+- Tokens expire after 30 seconds
+- One-time use (deleted after validation)
+- Secure random generation
+- Session validation before token acceptance
 
 ## Authelia Analysis
 
@@ -67,14 +122,20 @@ This allows the same session cookie to work across:
 
 ### Authentication Flow
 
-1. **User visits** `https://metube.aapamilne.com/`
-2. **Caddy forwards** to `http://clinch:9000/api/verify?rd=https://clinch.aapamilne.com`
+1. **User visits** `https://metube.example.com/`
+2. **Caddy forwards** to `http://clinch:9000/api/verify?rd=https://clinch.example.com`
 3. **Clinch checks session**:
    - **If authenticated**: Returns `200 OK` with user headers
    - **If not authenticated**: Returns `302 Found` to login URL with redirect parameters
 4. **Browser follows redirect** to Clinch login page
-5. **User logs in** → gets redirected back to original MEtube URL
-6. **Caddy tries again** → succeeds and forwards to MEtube
+5. **User logs in** (with TOTP if enabled):
+   - Rails creates session and sets cross-domain cookie
+   - **Rails generates one-time token** and appends to redirect URL
+   - User is redirected to: `https://metube.example.com/?fa_token=abc123...`
+6. **Browser follows redirect** → Caddy makes forward auth request with token
+7. **Clinch validates one-time token** → authenticates user immediately
+8. **Token is deleted** → subsequent requests use normal session cookies
+9. **Caddy forwards to MEtube** with proper authentication headers
 
 ### Response Headers
 
@@ -88,21 +149,21 @@ Remote-Admin: false
 
 **Redirect to Login (302 Found):**
 ```
-Location: https://clinch.aapamilne.com/signin?rd=https://metube.aapamilne.com/&rm=GET
+Location: https://clinch.example.com/signin?rd=https://metube.example.com/&rm=GET
 ```
 
 ## Caddy Configuration
 
 ```caddyfile
 # Clinch SSO (main authentication server)
-clinch.aapamilne.com {
+clinch.example.com {
     reverse_proxy clinch:9000
 }
 
 # MEtube (protected by Clinch)
-metube.aapamilne.com {
+metube.example.com {
     forward_auth clinch:9000 {
-        uri /api/verify?rd=https://clinch.aapamilne.com
+        uri /api/verify?rd=https://clinch.example.com
         copy_headers Remote-User Remote-Email Remote-Groups Remote-Admin
     }
 
@@ -126,7 +187,7 @@ metube.aapamilne.com {
 
 ```bash
 # Test forward auth endpoint directly
-curl -v http://localhost:9000/api/verify?rd=https://clinch.aapamilne.com
+curl -v http://localhost:9000/api/verify?rd=https://clinch.example.com
 
 # Should return 302 redirect to login page
 # Or 200 OK if you have a valid session cookie
@@ -139,6 +200,10 @@ curl -v http://localhost:9000/api/verify?rd=https://clinch.aapamilne.com
 1. **Authentication Loop**: Check that cookies are set on the root domain
 2. **Session Not Shared**: Verify `extract_root_domain` is working correctly
 3. **Caddy Connection**: Ensure `clinch:9000` resolves from your Caddy container
+4. **Race Condition After Authentication**:
+   - **Problem**: Forward auth fails immediately after login due to cookie timing
+   - **Solution**: One-time tokens automatically bridge this gap
+   - **Debug**: Look for "ForwardAuth: Valid one-time token used" in logs
 
 ### Debug Logging
 
@@ -146,8 +211,21 @@ Enable debug logging in `forward_auth_controller.rb` to see:
 - Headers received from Caddy
 - Domain extraction results
 - Redirect URLs being generated
+- Token validation during race condition resolution
 
 ```ruby
 Rails.logger.info "ForwardAuth Headers: Host=#{host}, X-Forwarded-Host=#{original_host}"
 Rails.logger.info "Setting 302 redirect to: #{login_url}"
+Rails.logger.info "ForwardAuth: Valid one-time token used for session #{session_id}"
+Rails.logger.info "Authentication: Added forward auth token to redirect URL: #{url}"
 ```
+
+**Key log messages to watch for:**
+- `"Authentication: Added forward auth token to redirect URL"` - Token generation during login
+- `"ForwardAuth: Valid one-time token used for session X"` - Successful race condition resolution
+- `"ForwardAuth: Session cookie present: false"` - Cookie timing issue (should be resolved by token)
+
+## Other References
+
+- https://www.reddit.com/r/selfhosted/comments/1hybe81/i_wanted_to_implement_my_own_forward_auth_proxy/
+- https://www.kevinsimper.dk/posts/implementing-a-forward_auth-proxy-tips-and-details