feat(auth): add authenticate callback for fallback logic

* Implement SetAuthenticateCallback in authenticators
* Update Authenticate methods to use callback on failure

pkg/security/chain.go

@@ -9,7 +9,8 @@ import (
 // ChainAuthenticator tries each authenticator in order, returning the first success.
 // Login and Logout are delegated to the primary authenticator.
 type ChainAuthenticator struct {
-	authenticators []Authenticator
+	authenticators       []Authenticator
+	authenticateCallback func(r *http.Request) (*UserContext, error)
 }
 
 // NewChainAuthenticator creates a ChainAuthenticator from the given authenticators.
@@ -29,13 +30,28 @@ func (c *ChainAuthenticator) Authenticate(r *http.Request) (*UserContext, error)
 			lastErr = err
 		}
 	}
+	if c.authenticateCallback != nil {
+		return c.authenticateCallback(r)
+	}
 	return nil, fmt.Errorf("all authenticators failed; last error: %w", lastErr)
 }
 
+func (c *ChainAuthenticator) SetAuthenticateCallback(fn func(r *http.Request) (*UserContext, error)) {
+	c.authenticateCallback = fn
+}
+
 func (c *ChainAuthenticator) Login(ctx context.Context, req LoginRequest) (*LoginResponse, error) {
 	return c.authenticators[0].Login(ctx, req)
 }
 
+func (c *ChainAuthenticator) LoginWithCookie(ctx context.Context, req LoginRequest, w http.ResponseWriter) (*LoginResponse, error) {
+	return c.authenticators[0].LoginWithCookie(ctx, req, w)
+}
+
 func (c *ChainAuthenticator) Logout(ctx context.Context, req LogoutRequest) error {
 	return c.authenticators[0].Logout(ctx, req)
 }
+
+func (c *ChainAuthenticator) LogoutWithCookie(ctx context.Context, req LogoutRequest, w http.ResponseWriter) error {
+	return c.authenticators[0].LogoutWithCookie(ctx, req, w)
+}

pkg/security/chain_test.go

@@ -25,10 +25,20 @@ func (s *stubAuthenticator) Login(_ context.Context, _ LoginRequest) (*LoginResp
 	return &LoginResponse{Token: "tok"}, nil
 }
 
+func (s *stubAuthenticator) LoginWithCookie(ctx context.Context, req LoginRequest, _ http.ResponseWriter) (*LoginResponse, error) {
+	return s.Login(ctx, req)
+}
+
 func (s *stubAuthenticator) Logout(_ context.Context, _ LogoutRequest) error {
 	return s.err
 }
 
+func (s *stubAuthenticator) LogoutWithCookie(ctx context.Context, req LogoutRequest, _ http.ResponseWriter) error {
+	return s.Logout(ctx, req)
+}
+
+func (s *stubAuthenticator) SetAuthenticateCallback(_ func(r *http.Request) (*UserContext, error)) {}
+
 func TestChainAuthenticator_Authenticate(t *testing.T) {
 	successCtx := &UserContext{UserID: 42, UserName: "alice"}
 	failStub := &stubAuthenticator{err: fmt.Errorf("no token")}

pkg/security/composite.go

@@ -43,16 +43,31 @@ func (c *CompositeSecurityProvider) Login(ctx context.Context, req LoginRequest)
 	return c.auth.Login(ctx, req)
 }
 
+// LoginWithCookie delegates to the authenticator
+func (c *CompositeSecurityProvider) LoginWithCookie(ctx context.Context, req LoginRequest, w http.ResponseWriter) (*LoginResponse, error) {
+	return c.auth.LoginWithCookie(ctx, req, w)
+}
+
 // Logout delegates to the authenticator
 func (c *CompositeSecurityProvider) Logout(ctx context.Context, req LogoutRequest) error {
 	return c.auth.Logout(ctx, req)
 }
 
+// LogoutWithCookie delegates to the authenticator
+func (c *CompositeSecurityProvider) LogoutWithCookie(ctx context.Context, req LogoutRequest, w http.ResponseWriter) error {
+	return c.auth.LogoutWithCookie(ctx, req, w)
+}
+
 // Authenticate delegates to the authenticator
 func (c *CompositeSecurityProvider) Authenticate(r *http.Request) (*UserContext, error) {
 	return c.auth.Authenticate(r)
 }
 
+// SetAuthenticateCallback delegates to the authenticator
+func (c *CompositeSecurityProvider) SetAuthenticateCallback(fn func(r *http.Request) (*UserContext, error)) {
+	c.auth.SetAuthenticateCallback(fn)
+}
+
 // GetColumnSecurity delegates to the column security provider
 func (c *CompositeSecurityProvider) GetColumnSecurity(ctx context.Context, userID int, schema, table string) ([]ColumnSecurity, error) {
 	return c.colSec.GetColumnSecurity(ctx, userID, schema, table)

pkg/security/composite_test.go

@@ -23,14 +23,24 @@ func (m *mockAuth) Login(ctx context.Context, req LoginRequest) (*LoginResponse,
 	return m.loginResp, m.loginErr
 }
 
+func (m *mockAuth) LoginWithCookie(ctx context.Context, req LoginRequest, _ http.ResponseWriter) (*LoginResponse, error) {
+	return m.Login(ctx, req)
+}
+
 func (m *mockAuth) Logout(ctx context.Context, req LogoutRequest) error {
 	return m.logoutErr
 }
 
+func (m *mockAuth) LogoutWithCookie(ctx context.Context, req LogoutRequest, _ http.ResponseWriter) error {
+	return m.Logout(ctx, req)
+}
+
 func (m *mockAuth) Authenticate(r *http.Request) (*UserContext, error) {
 	return m.authUser, m.authErr
 }
 
+func (m *mockAuth) SetAuthenticateCallback(_ func(r *http.Request) (*UserContext, error)) {}
+
 // Optional interface implementations
 func (m *mockAuth) RefreshToken(ctx context.Context, refreshToken string) (*LoginResponse, error) {
 	if !m.supportsRefresh {

pkg/security/interfaces.go

@@ -83,12 +83,26 @@ type Authenticator interface {
 	// Login authenticates credentials and returns a token
 	Login(ctx context.Context, req LoginRequest) (*LoginResponse, error)
 
+	// LoginWithCookie authenticates credentials and, when cookie sessions are enabled,
+	// writes the session cookie to w. Implementations that do not support cookies
+	// should delegate to Login and ignore w.
+	LoginWithCookie(ctx context.Context, req LoginRequest, w http.ResponseWriter) (*LoginResponse, error)
+
 	// Logout invalidates a user's session/token
 	Logout(ctx context.Context, req LogoutRequest) error
 
+	// LogoutWithCookie invalidates a user's session/token and, when cookie sessions are
+	// enabled, clears the session cookie on w. Implementations that do not support cookies
+	// should delegate to Logout and ignore w.
+	LogoutWithCookie(ctx context.Context, req LogoutRequest, w http.ResponseWriter) error
+
 	// Authenticate extracts and validates user from HTTP request
 	// Returns UserContext or error if authentication fails
 	Authenticate(r *http.Request) (*UserContext, error)
+
+	// SetAuthenticateCallback registers a fallback called when primary authentication fails.
+	// If the callback returns a non-nil UserContext, that result is used instead of the error.
+	SetAuthenticateCallback(fn func(r *http.Request) (*UserContext, error))
 }
 
 // Registrable allows providers to support user registration

pkg/security/keystore_authenticator.go

@@ -17,8 +17,9 @@ import (
 //  2. Authorization: ApiKey <key>
 //  3. X-API-Key header
 type KeyStoreAuthenticator struct {
-	keyStore KeyStore
-	keyType  KeyType // empty = accept any type
+	keyStore             KeyStore
+	keyType              KeyType // empty = accept any type
+	authenticateCallback func(r *http.Request) (*UserContext, error)
 }
 
 // NewKeyStoreAuthenticator creates a KeyStoreAuthenticator.
@@ -32,21 +33,42 @@ func (a *KeyStoreAuthenticator) Login(_ context.Context, _ LoginRequest) (*Login
 	return nil, fmt.Errorf("keystore authenticator does not support login")
 }
 
+// LoginWithCookie is not supported for keystore authentication.
+func (a *KeyStoreAuthenticator) LoginWithCookie(_ context.Context, _ LoginRequest, _ http.ResponseWriter) (*LoginResponse, error) {
+	return nil, fmt.Errorf("keystore authenticator does not support login")
+}
+
 // Logout is not supported for keystore authentication.
 func (a *KeyStoreAuthenticator) Logout(_ context.Context, _ LogoutRequest) error {
 	return nil
 }
 
+// LogoutWithCookie is not supported for keystore authentication.
+func (a *KeyStoreAuthenticator) LogoutWithCookie(_ context.Context, _ LogoutRequest, _ http.ResponseWriter) error {
+	return nil
+}
+
+// SetAuthenticateCallback registers a fallback called when key authentication fails.
+func (a *KeyStoreAuthenticator) SetAuthenticateCallback(fn func(r *http.Request) (*UserContext, error)) {
+	a.authenticateCallback = fn
+}
+
 // Authenticate extracts an API key from the request and validates it against the KeyStore.
 // Returns a UserContext built from the matching UserKey on success.
 func (a *KeyStoreAuthenticator) Authenticate(r *http.Request) (*UserContext, error) {
 	rawKey := extractAPIKey(r)
 	if rawKey == "" {
+		if a.authenticateCallback != nil {
+			return a.authenticateCallback(r)
+		}
 		return nil, fmt.Errorf("API key required (Authorization: Bearer/ApiKey <key> or X-API-Key header)")
 	}
 
 	userKey, err := a.keyStore.ValidateKey(r.Context(), rawKey, a.keyType)
 	if err != nil {
+		if a.authenticateCallback != nil {
+			return a.authenticateCallback(r)
+		}
 		return nil, fmt.Errorf("invalid API key: %w", err)
 	}
 

pkg/security/provider_test.go

@@ -22,14 +22,24 @@ func (m *mockSecurityProvider) Login(ctx context.Context, req LoginRequest) (*Lo
 	return m.loginResponse, m.loginError
 }
 
+func (m *mockSecurityProvider) LoginWithCookie(ctx context.Context, req LoginRequest, _ http.ResponseWriter) (*LoginResponse, error) {
+	return m.Login(ctx, req)
+}
+
 func (m *mockSecurityProvider) Logout(ctx context.Context, req LogoutRequest) error {
 	return m.logoutError
 }
 
+func (m *mockSecurityProvider) LogoutWithCookie(ctx context.Context, req LogoutRequest, _ http.ResponseWriter) error {
+	return m.Logout(ctx, req)
+}
+
 func (m *mockSecurityProvider) Authenticate(r *http.Request) (*UserContext, error) {
 	return m.authUser, m.authError
 }
 
+func (m *mockSecurityProvider) SetAuthenticateCallback(_ func(r *http.Request) (*UserContext, error)) {}
+
 func (m *mockSecurityProvider) GetColumnSecurity(ctx context.Context, userID int, schema, table string) ([]ColumnSecurity, error) {
 	return m.columnSecurity, nil
 }

pkg/security/providers.go

@@ -30,10 +30,18 @@ func (a *HeaderAuthenticator) Login(ctx context.Context, req LoginRequest) (*Log
 	return nil, fmt.Errorf("header authentication does not support login")
 }
 
+func (a *HeaderAuthenticator) LoginWithCookie(ctx context.Context, req LoginRequest, w http.ResponseWriter) (*LoginResponse, error) {
+	return a.Login(ctx, req)
+}
+
 func (a *HeaderAuthenticator) Logout(ctx context.Context, req LogoutRequest) error {
 	return nil
 }
 
+func (a *HeaderAuthenticator) LogoutWithCookie(ctx context.Context, req LogoutRequest, w http.ResponseWriter) error {
+	return a.Logout(ctx, req)
+}
+
 func (a *HeaderAuthenticator) Authenticate(r *http.Request) (*UserContext, error) {
 	userIDStr := r.Header.Get("X-User-ID")
 	if userIDStr == "" {
@@ -80,6 +88,9 @@ type DatabaseAuthenticator struct {
 
 	// Passkey provider (optional)
 	passkeyProvider PasskeyProvider
+
+	// Optional fallback called when primary authentication fails
+	authenticateCallback func(r *http.Request) (*UserContext, error)
 }
 
 // DatabaseAuthenticatorOptions configures the database authenticator
@@ -105,6 +116,10 @@ type DatabaseAuthenticatorOptions struct {
 	// CookieOptions configures the session cookie written by LoginWithCookie.
 	// Only used when EnableCookieSession is true.
 	CookieOptions SessionCookieOptions
+	// AuthenticateCallback is a fallback called when the primary authentication (database
+	// session lookup) fails. If non-nil and the callback returns a non-nil UserContext,
+	// that result is used in place of the failure.
+	AuthenticateCallback func(r *http.Request) (*UserContext, error)
 }
 
 func NewDatabaseAuthenticator(db *sql.DB) *DatabaseAuthenticator {
@@ -126,14 +141,15 @@ func NewDatabaseAuthenticatorWithOptions(db *sql.DB, opts DatabaseAuthenticatorO
 	sqlNames := MergeSQLNames(DefaultSQLNames(), opts.SQLNames)
 
 	return &DatabaseAuthenticator{
-		db:                  db,
-		dbFactory:           opts.DBFactory,
-		cache:               cacheInstance,
-		cacheTTL:            opts.CacheTTL,
-		sqlNames:            sqlNames,
-		passkeyProvider:     opts.PasskeyProvider,
-		enableCookieSession: opts.EnableCookieSession,
-		cookieOptions:       opts.CookieOptions,
+		db:                   db,
+		dbFactory:            opts.DBFactory,
+		cache:                cacheInstance,
+		cacheTTL:             opts.CacheTTL,
+		sqlNames:             sqlNames,
+		passkeyProvider:      opts.PasskeyProvider,
+		enableCookieSession:  opts.EnableCookieSession,
+		cookieOptions:        opts.CookieOptions,
+		authenticateCallback: opts.AuthenticateCallback,
 	}
 }
 
@@ -173,6 +189,10 @@ func (a *DatabaseAuthenticator) runDBOpWithReconnect(run func(*sql.DB) error) er
 	return err
 }
 
+func (a *DatabaseAuthenticator) SetAuthenticateCallback(fn func(r *http.Request) (*UserContext, error)) {
+	a.authenticateCallback = fn
+}
+
 func (a *DatabaseAuthenticator) Login(ctx context.Context, req LoginRequest) (*LoginResponse, error) {
 	// Convert LoginRequest to JSON
 	reqJSON, err := json.Marshal(req)
@@ -337,6 +357,9 @@ func (a *DatabaseAuthenticator) Authenticate(r *http.Request) (*UserContext, err
 	}
 
 	if len(tokens) == 0 {
+		if a.authenticateCallback != nil {
+			return a.authenticateCallback(r)
+		}
 		return nil, fmt.Errorf("session token required")
 	}
 
@@ -399,7 +422,10 @@ func (a *DatabaseAuthenticator) Authenticate(r *http.Request) (*UserContext, err
 		return &userCtx, nil
 	}
 
-	// All tokens failed
+	// All tokens failed — try callback before returning error
+	if a.authenticateCallback != nil {
+		return a.authenticateCallback(r)
+	}
 	if lastErr != nil {
 		return nil, lastErr
 	}
@@ -625,6 +651,14 @@ func (a *JWTAuthenticator) Logout(ctx context.Context, req LogoutRequest) error
 	return nil
 }
 
+func (a *JWTAuthenticator) LoginWithCookie(ctx context.Context, req LoginRequest, w http.ResponseWriter) (*LoginResponse, error) {
+	return a.Login(ctx, req)
+}
+
+func (a *JWTAuthenticator) LogoutWithCookie(ctx context.Context, req LogoutRequest, w http.ResponseWriter) error {
+	return a.Logout(ctx, req)
+}
+
 func (a *JWTAuthenticator) Authenticate(r *http.Request) (*UserContext, error) {
 	authHeader := r.Header.Get("Authorization")
 	if authHeader == "" {

pkg/security/providers_test.go

@@ -511,6 +511,10 @@ func TestDatabaseAuthenticator(t *testing.T) {
 	})
 
 	t.Run("authenticate with cookie", func(t *testing.T) {
+		cookieAuth := NewDatabaseAuthenticatorWithOptions(db, DatabaseAuthenticatorOptions{
+			EnableCookieSession: true,
+		})
+
 		req := httptest.NewRequest("GET", "/test", nil)
 		req.AddCookie(&http.Cookie{
 			Name:  "session_token",
@@ -524,7 +528,7 @@ func TestDatabaseAuthenticator(t *testing.T) {
 			WithArgs("cookie-token-456", "cookie").
 			WillReturnRows(rows)
 
-		userCtx, err := auth.Authenticate(req)
+		userCtx, err := cookieAuth.Authenticate(req)
 		if err != nil {
 			t.Fatalf("expected no error, got %v", err)
 		}

pkg/security/totp_integration_test.go

@@ -43,14 +43,24 @@ func (m *MockAuthenticator) Login(ctx context.Context, req security.LoginRequest
 	}, nil
 }
 
+func (m *MockAuthenticator) LoginWithCookie(ctx context.Context, req security.LoginRequest, _ http.ResponseWriter) (*security.LoginResponse, error) {
+	return m.Login(ctx, req)
+}
+
 func (m *MockAuthenticator) Logout(ctx context.Context, req security.LogoutRequest) error {
 	return nil
 }
 
+func (m *MockAuthenticator) LogoutWithCookie(ctx context.Context, req security.LogoutRequest, _ http.ResponseWriter) error {
+	return m.Logout(ctx, req)
+}
+
 func (m *MockAuthenticator) Authenticate(r *http.Request) (*security.UserContext, error) {
 	return m.users["testuser"], nil
 }
 
+func (m *MockAuthenticator) SetAuthenticateCallback(_ func(r *http.Request) (*security.UserContext, error)) {}
+
 func TestTwoFactorAuthenticator_Setup(t *testing.T) {
 	baseAuth := NewMockAuthenticator()
 	provider := security.NewMemoryTwoFactorProvider(nil)