feat(staticweb): enhance fallback logic for extensionless paths

* Added support for serving index.html for extensionless paths
* Updated isStaticAsset to exclude paths without extensions from static asset checks

pkg/common/adapters/database/bun.go

@@ -1315,6 +1315,7 @@ func (b *BunSelectQuery) Scan(ctx context.Context, dest interface{}) (err error)
 	if err != nil {
 		sqlStr := b.query.String()
 		logger.Error("BunSelectQuery.Scan failed. SQL: %s. Error: %v", sqlStr, err)
+		err = common.WrapSQLError(err, sqlStr)
 	}
 	return err
 }
@@ -1371,7 +1372,7 @@ func (b *BunSelectQuery) ScanModel(ctx context.Context) (err error) {
 	if err != nil {
 		sqlStr := b.query.String()
 		logger.Error("BunSelectQuery.ScanModel failed. SQL: %s. Error: %v", sqlStr, err)
-		return err
+		return common.WrapSQLError(err, sqlStr)
 	}
 
 	// After main query, load custom preloads using separate queries
@@ -1401,6 +1402,7 @@ func (b *BunSelectQuery) Count(ctx context.Context) (count int, err error) {
 		if err != nil {
 			sqlStr := b.query.String()
 			logger.Error("BunSelectQuery.Count failed. SQL: %s. Error: %v", sqlStr, err)
+			err = common.WrapSQLError(err, sqlStr)
 		}
 		return
 	}
@@ -1414,6 +1416,7 @@ func (b *BunSelectQuery) Count(ctx context.Context) (count int, err error) {
 	if err != nil {
 		sqlStr := countQuery.String()
 		logger.Error("BunSelectQuery.Count (subquery) failed. SQL: %s. Error: %v", sqlStr, err)
+		err = common.WrapSQLError(err, sqlStr)
 	}
 	return
 }
@@ -1431,6 +1434,7 @@ func (b *BunSelectQuery) Exists(ctx context.Context) (exists bool, err error) {
 	if err != nil {
 		sqlStr := b.query.String()
 		logger.Error("BunSelectQuery.Exists failed. SQL: %s. Error: %v", sqlStr, err)
+		err = common.WrapSQLError(err, sqlStr)
 	}
 	return
 }
@@ -1619,6 +1623,7 @@ func (b *BunUpdateQuery) Exec(ctx context.Context) (res common.Result, err error
 		// Log SQL string for debugging
 		sqlStr := b.query.String()
 		logger.Error("BunUpdateQuery.Exec failed. SQL: %s. Error: %v", sqlStr, err)
+		err = common.WrapSQLError(err, sqlStr)
 	}
 	recordQueryMetrics(b.metricsEnabled, "UPDATE", b.schema, b.entity, b.tableName, startedAt, err)
 	return &BunResult{result: result}, err
@@ -1670,6 +1675,7 @@ func (b *BunDeleteQuery) Exec(ctx context.Context) (res common.Result, err error
 		// Log SQL string for debugging
 		sqlStr := b.query.String()
 		logger.Error("BunDeleteQuery.Exec failed. SQL: %s. Error: %v", sqlStr, err)
+		err = common.WrapSQLError(err, sqlStr)
 	}
 	recordQueryMetrics(b.metricsEnabled, "DELETE", b.schema, b.entity, b.tableName, startedAt, err)
 	return &BunResult{result: result}, err

pkg/common/adapters/database/gorm.go

@@ -583,6 +583,7 @@ func (g *GormSelectQuery) Scan(ctx context.Context, dest interface{}) (err error
 			return tx.Find(dest)
 		})
 		logger.Error("GormSelectQuery.Scan failed. SQL: %s. Error: %v", sqlStr, err)
+		err = common.WrapSQLError(err, sqlStr)
 	}
 	recordQueryMetrics(g.metricsEnabled, "SELECT", g.schema, g.entity, g.tableName, startedAt, err)
 	return err
@@ -613,6 +614,7 @@ func (g *GormSelectQuery) ScanModel(ctx context.Context) (err error) {
 			return tx.Find(g.db.Statement.Model)
 		})
 		logger.Error("GormSelectQuery.ScanModel failed. SQL: %s. Error: %v", sqlStr, err)
+		err = common.WrapSQLError(err, sqlStr)
 	}
 	recordQueryMetrics(g.metricsEnabled, "SELECT", g.schema, g.entity, g.tableName, startedAt, err)
 	return err
@@ -642,6 +644,7 @@ func (g *GormSelectQuery) Count(ctx context.Context) (count int, err error) {
 			return tx.Count(&count64)
 		})
 		logger.Error("GormSelectQuery.Count failed. SQL: %s. Error: %v", sqlStr, err)
+		err = common.WrapSQLError(err, sqlStr)
 	}
 	recordQueryMetrics(g.metricsEnabled, "COUNT", g.schema, g.entity, g.tableName, startedAt, err)
 	return int(count64), err
@@ -671,6 +674,7 @@ func (g *GormSelectQuery) Exists(ctx context.Context) (exists bool, err error) {
 			return tx.Limit(1).Count(&count)
 		})
 		logger.Error("GormSelectQuery.Exists failed. SQL: %s. Error: %v", sqlStr, err)
+		err = common.WrapSQLError(err, sqlStr)
 	}
 	recordQueryMetrics(g.metricsEnabled, "EXISTS", g.schema, g.entity, g.tableName, startedAt, err)
 	return count > 0, err
@@ -931,6 +935,7 @@ func (g *GormUpdateQuery) Exec(ctx context.Context) (res common.Result, err erro
 			return tx.Updates(g.updates)
 		})
 		logger.Error("GormUpdateQuery.Exec failed. SQL: %s. Error: %v", sqlStr, result.Error)
+		return &GormResult{result: result}, common.WrapSQLError(result.Error, sqlStr)
 	}
 	recordQueryMetrics(g.metricsEnabled, "UPDATE", g.schema, g.entity, g.tableName, startedAt, result.Error)
 	return &GormResult{result: result}, result.Error
@@ -992,6 +997,7 @@ func (g *GormDeleteQuery) Exec(ctx context.Context) (res common.Result, err erro
 			return tx.Delete(g.model)
 		})
 		logger.Error("GormDeleteQuery.Exec failed. SQL: %s. Error: %v", sqlStr, result.Error)
+		return &GormResult{result: result}, common.WrapSQLError(result.Error, sqlStr)
 	}
 	recordQueryMetrics(g.metricsEnabled, "DELETE", g.schema, g.entity, g.tableName, startedAt, result.Error)
 	return &GormResult{result: result}, result.Error

pkg/common/adapters/database/pgsql.go

@@ -138,7 +138,7 @@ func (p *PgSQLAdapter) Exec(ctx context.Context, query string, args ...interface
 	if err != nil {
 		logger.Error("PgSQL Exec failed: %v", err)
 		recordQueryMetrics(p.metricsEnabled, operation, schema, entity, table, startedAt, err)
-		return nil, err
+		return nil, common.WrapSQLError(err, query)
 	}
 	recordQueryMetrics(p.metricsEnabled, operation, schema, entity, table, startedAt, nil)
 	return &PgSQLResult{result: result}, nil
@@ -164,7 +164,7 @@ func (p *PgSQLAdapter) Query(ctx context.Context, dest interface{}, query string
 	if err != nil {
 		logger.Error("PgSQL Query failed: %v", err)
 		recordQueryMetrics(p.metricsEnabled, operation, schema, entity, table, startedAt, err)
-		return err
+		return common.WrapSQLError(err, query)
 	}
 	defer rows.Close()
 
@@ -511,7 +511,7 @@ func (p *PgSQLSelectQuery) Scan(ctx context.Context, dest interface{}) (err erro
 	if err != nil {
 		logger.Error("PgSQL SELECT failed: %v", err)
 		recordQueryMetrics(p.metricsEnabled, "SELECT", p.schema, p.entity, p.tableName, startedAt, err)
-		return err
+		return common.WrapSQLError(err, query)
 	}
 	defer rows.Close()
 
@@ -534,8 +534,8 @@ func (p *PgSQLSelectQuery) ScanModel(ctx context.Context) error {
 	return p.Scan(ctx, p.model)
 }
 
-// countInternal executes the COUNT query and returns the result without recording metrics.
-func (p *PgSQLSelectQuery) countInternal(ctx context.Context) (int, error) {
+// countInternal executes the COUNT query and returns the result and the SQL string without recording metrics.
+func (p *PgSQLSelectQuery) countInternal(ctx context.Context) (rowCount int, querySQL string, retErr error) {
 	var sb strings.Builder
 	sb.WriteString("SELECT COUNT(*) FROM ")
 	sb.WriteString(p.tableName)
@@ -571,9 +571,9 @@ func (p *PgSQLSelectQuery) countInternal(ctx context.Context) (int, error) {
 
 	var count int
 	if err := row.Scan(&count); err != nil {
-		return 0, err
+		return 0, query, err
 	}
-	return count, nil
+	return count, query, nil
 }
 
 func (p *PgSQLSelectQuery) Count(ctx context.Context) (count int, err error) {
@@ -584,9 +584,11 @@ func (p *PgSQLSelectQuery) Count(ctx context.Context) (count int, err error) {
 		}
 	}()
 	startedAt := time.Now()
-	count, err = p.countInternal(ctx)
+	var sqlStr string
+	count, sqlStr, err = p.countInternal(ctx)
 	if err != nil {
 		logger.Error("PgSQL COUNT failed: %v", err)
+		err = common.WrapSQLError(err, sqlStr)
 	}
 	recordQueryMetrics(p.metricsEnabled, "COUNT", p.schema, p.entity, p.tableName, startedAt, err)
 	return count, err
@@ -600,9 +602,11 @@ func (p *PgSQLSelectQuery) Exists(ctx context.Context) (exists bool, err error)
 		}
 	}()
 	startedAt := time.Now()
-	count, err := p.countInternal(ctx)
+	var sqlStr string
+	count, sqlStr, err := p.countInternal(ctx)
 	if err != nil {
 		logger.Error("PgSQL EXISTS failed: %v", err)
+		err = common.WrapSQLError(err, sqlStr)
 	}
 	recordQueryMetrics(p.metricsEnabled, "EXISTS", p.schema, p.entity, p.tableName, startedAt, err)
 	return count > 0, err
@@ -702,7 +706,7 @@ func (p *PgSQLInsertQuery) Exec(ctx context.Context) (res common.Result, err err
 
 	if err != nil {
 		logger.Error("PgSQL INSERT failed: %v", err)
-		return nil, err
+		return nil, common.WrapSQLError(err, query)
 	}
 
 	return &PgSQLResult{result: result}, nil
@@ -750,7 +754,10 @@ func (p *PgSQLInsertQuery) Scan(ctx context.Context, dest interface{}) (err erro
 		row = p.db.QueryRowContext(ctx, query, args...)
 	}
 
-	return row.Scan(dest)
+	if err := row.Scan(dest); err != nil {
+		return common.WrapSQLError(err, query)
+	}
+	return nil
 }
 
 // PgSQLUpdateQuery implements UpdateQuery for PostgreSQL
@@ -929,7 +936,7 @@ func (p *PgSQLUpdateQuery) Exec(ctx context.Context) (res common.Result, err err
 
 	if err != nil {
 		logger.Error("PgSQL UPDATE failed: %v", err)
-		return nil, err
+		return nil, common.WrapSQLError(err, query)
 	}
 
 	return &PgSQLResult{result: result}, nil
@@ -1007,7 +1014,7 @@ func (p *PgSQLDeleteQuery) Exec(ctx context.Context) (res common.Result, err err
 
 	if err != nil {
 		logger.Error("PgSQL DELETE failed: %v", err)
-		return nil, err
+		return nil, common.WrapSQLError(err, query)
 	}
 
 	return &PgSQLResult{result: result}, nil
@@ -1088,7 +1095,7 @@ func (p *PgSQLTxAdapter) Exec(ctx context.Context, query string, args ...interfa
 	if err != nil {
 		logger.Error("PgSQL Tx Exec failed: %v", err)
 		recordQueryMetrics(p.metricsEnabled, operation, schema, entity, table, startedAt, err)
-		return nil, err
+		return nil, common.WrapSQLError(err, query)
 	}
 	recordQueryMetrics(p.metricsEnabled, operation, schema, entity, table, startedAt, nil)
 	return &PgSQLResult{result: result}, nil
@@ -1102,7 +1109,7 @@ func (p *PgSQLTxAdapter) Query(ctx context.Context, dest interface{}, query stri
 	if err != nil {
 		logger.Error("PgSQL Tx Query failed: %v", err)
 		recordQueryMetrics(p.metricsEnabled, operation, schema, entity, table, startedAt, err)
-		return err
+		return common.WrapSQLError(err, query)
 	}
 	defer rows.Close()
 

pkg/common/types.go

@@ -1,5 +1,23 @@
 package common
 
+// SQLError wraps a database error together with the SQL that caused it,
+// so callers can surface the query in API error responses for easier debugging.
+type SQLError struct {
+	Err error
+	SQL string
+}
+
+func (e *SQLError) Error() string { return e.Err.Error() }
+func (e *SQLError) Unwrap() error { return e.Err }
+
+// WrapSQLError wraps err with the given SQL. If err is nil it returns nil.
+func WrapSQLError(err error, sql string) error {
+	if err == nil {
+		return nil
+	}
+	return &SQLError{Err: err, SQL: sql}
+}
+
 type RequestBody struct {
 	Operation string         `json:"operation"`
 	Data      interface{}    `json:"data"`
@@ -104,6 +122,7 @@ type APIError struct {
 	Message string      `json:"message"`
 	Details interface{} `json:"details,omitempty"`
 	Detail  string      `json:"detail,omitempty"`
+	SQL     string      `json:"sql,omitempty"`
 }
 
 type Column struct {

pkg/funcspec/function_api.go

@@ -3,6 +3,7 @@ package funcspec
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -1071,6 +1072,10 @@ func sendError(w http.ResponseWriter, status int, code, message string, err erro
 	}
 	if err != nil {
 		errObj.Detail = err.Error()
+		var sqlErr *common.SQLError
+		if errors.As(err, &sqlErr) {
+			errObj.SQL = sqlErr.SQL
+		}
 	}
 
 	data, _ := json.Marshal(map[string]interface{}{

pkg/resolvespec/handler.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"database/sql"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"net/http"
 	"reflect"
@@ -1757,18 +1758,21 @@ func (h *Handler) sendResponse(w common.ResponseWriter, data interface{}, metada
 }
 
 func (h *Handler) sendError(w common.ResponseWriter, status int, code, message string, details interface{}) {
-	w.SetHeader("Content-Type", "application/json")
-	w.WriteHeader(status)
-	err := w.WriteJSON(common.Response{
-		Success: false,
-		Error: &common.APIError{
+	apiErr := &common.APIError{
 		Code:    code,
 		Message: message,
 		Details: details,
 		Detail:  fmt.Sprintf("%v", details),
-		},
-	})
-	if err != nil {
+	}
+	if asErr, ok := details.(error); ok {
+		var sqlErr *common.SQLError
+		if errors.As(asErr, &sqlErr) {
+			apiErr.SQL = sqlErr.SQL
+		}
+	}
+	w.SetHeader("Content-Type", "application/json")
+	w.WriteHeader(status)
+	if err := w.WriteJSON(common.Response{Success: false, Error: apiErr}); err != nil {
 		logger.Error("Error sending response: %v", err)
 	}
 }

pkg/restheadspec/handler.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"database/sql"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"net/http"
 	"reflect"
@@ -579,8 +580,8 @@ func (h *Handler) handleRead(ctx context.Context, w common.ResponseWriter, id st
 	// preload LEFT JOIN (to prevent "table name specified more than once" errors).
 	if len(options.CustomSQLJoin) > 0 {
 		preloadAliasSet := make(map[string]bool, len(options.Preload))
-		for _, p := range options.Preload {
-			if alias := common.RelationPathToBunAlias(p.Relation); alias != "" {
+		for i := range options.Preload {
+			if alias := common.RelationPathToBunAlias(options.Preload[i].Relation); alias != "" {
 				preloadAliasSet[alias] = true
 			}
 		}
@@ -619,16 +620,19 @@ func (h *Handler) handleRead(ctx context.Context, w common.ResponseWriter, id st
 		logger.Debug("FetchRowNumber: Row number %d for PK %s = %s", rowNum, pkName, fetchRowNumberPKValue)
 
 		// Now filter the main query to this specific primary key
-		query = query.Where(fmt.Sprintf("%s = ?", common.QuoteIdent(pkName)), fetchRowNumberPKValue)
+		tableAlias := reflection.ExtractTableNameOnly(tableName)
+		query = query.Where(fmt.Sprintf("%s.%s = ?", common.QuoteIdent(tableAlias), common.QuoteIdent(pkName)), fetchRowNumberPKValue)
 	} else if id != "" {
 		// If ID is provided (and not FetchRowNumber), filter by ID
 		pkName := reflection.GetPrimaryKeyName(model)
 		logger.Debug("Filtering by ID=%s: %s", pkName, id)
 
-		query = query.Where(fmt.Sprintf("%s = ?", common.QuoteIdent(pkName)), id)
+		tableAlias := reflection.ExtractTableNameOnly(tableName)
+		query = query.Where(fmt.Sprintf("%s.%s = ?", common.QuoteIdent(tableAlias), common.QuoteIdent(pkName)), id)
 	}
 
 	// Apply sorting
+	tableAlias := reflection.ExtractTableNameOnly(tableName)
 	for _, sort := range options.Sort {
 		direction := "ASC"
 		if strings.EqualFold(sort.Direction, "desc") {
@@ -640,9 +644,12 @@ func (h *Handler) handleRead(ctx context.Context, w common.ResponseWriter, id st
 		if strings.HasPrefix(sort.Column, "(") && strings.HasSuffix(sort.Column, ")") {
 			// For expressions, pass as raw SQL to prevent auto-quoting
 			query = query.OrderExpr(fmt.Sprintf("%s %s", sort.Column, direction))
+		} else if strings.Contains(sort.Column, ".") {
+			// Already qualified (e.g. alias.column) - pass as raw expression to preserve the dot
+			query = query.OrderExpr(fmt.Sprintf("%s %s", sort.Column, direction))
 		} else {
-			// Regular column - let Bun handle quoting
-			query = query.Order(fmt.Sprintf("%s %s", sort.Column, direction))
+			// Unqualified column - prefix with main table alias to avoid ambiguity on JOINs
+			query = query.OrderExpr(fmt.Sprintf("%s.%s %s", common.QuoteIdent(tableAlias), common.QuoteIdent(sort.Column), direction))
 		}
 	}
 
@@ -1360,7 +1367,7 @@ func (h *Handler) handleUpdate(ctx context.Context, w common.ResponseWriter, id
 
 		// First, read the existing record from the database
 		existingRecord := reflect.New(reflection.GetPointerElement(reflect.TypeOf(model))).Interface()
-		selectQuery := tx.NewSelect().Model(existingRecord).Column("*").Where(fmt.Sprintf("%s = ?", common.QuoteIdent(pkName)), targetID)
+		selectQuery := tx.NewSelect().Model(existingRecord).Where(fmt.Sprintf("%s = ?", common.QuoteIdent(pkName)), targetID)
 		if err := selectQuery.ScanModel(ctx); err != nil {
 			if err == sql.ErrNoRows {
 				return fmt.Errorf("record not found with ID: %v", targetID)
@@ -2639,6 +2646,12 @@ func (h *Handler) sendError(w common.ResponseWriter, statusCode int, code, messa
 		"_error":  errorMsg,
 		"_retval": 1,
 	}
+
+	var sqlErr *common.SQLError
+	if errors.As(err, &sqlErr) {
+		response["_sql"] = sqlErr.SQL
+	}
+
 	w.SetHeader("Content-Type", "application/json")
 	w.WriteHeader(statusCode)
 	if jsonErr := w.WriteJSON(response); jsonErr != nil {

pkg/security/chain.go

@@ -0,0 +1,57 @@
+package security
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+)
+
+// ChainAuthenticator tries each authenticator in order, returning the first success.
+// Login and Logout are delegated to the primary authenticator.
+type ChainAuthenticator struct {
+	authenticators       []Authenticator
+	authenticateCallback func(r *http.Request) (*UserContext, error)
+}
+
+// NewChainAuthenticator creates a ChainAuthenticator from the given authenticators.
+// At least one authenticator is required; the first is treated as primary for Login/Logout.
+func NewChainAuthenticator(primary Authenticator, rest ...Authenticator) *ChainAuthenticator {
+	return &ChainAuthenticator{
+		authenticators: append([]Authenticator{primary}, rest...),
+	}
+}
+
+func (c *ChainAuthenticator) Authenticate(r *http.Request) (*UserContext, error) {
+	var lastErr error
+	for _, a := range c.authenticators {
+		if uc, err := a.Authenticate(r); err == nil {
+			return uc, nil
+		} else {
+			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

@@ -0,0 +1,127 @@
+package security
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+// stubAuthenticator is a configurable Authenticator for testing.
+type stubAuthenticator struct {
+	userCtx *UserContext
+	err     error
+}
+
+func (s *stubAuthenticator) Authenticate(_ *http.Request) (*UserContext, error) {
+	return s.userCtx, s.err
+}
+
+func (s *stubAuthenticator) Login(_ context.Context, _ LoginRequest) (*LoginResponse, error) {
+	if s.err != nil {
+		return nil, s.err
+	}
+	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")}
+	okStub := &stubAuthenticator{userCtx: successCtx}
+
+	t.Run("primary succeeds", func(t *testing.T) {
+		chain := NewChainAuthenticator(okStub, failStub)
+		req := httptest.NewRequest("GET", "/", nil)
+
+		uc, err := chain.Authenticate(req)
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if uc.UserID != 42 {
+			t.Errorf("expected UserID 42, got %d", uc.UserID)
+		}
+	})
+
+	t.Run("primary fails, secondary succeeds", func(t *testing.T) {
+		chain := NewChainAuthenticator(failStub, okStub)
+		req := httptest.NewRequest("GET", "/", nil)
+
+		uc, err := chain.Authenticate(req)
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if uc.UserID != 42 {
+			t.Errorf("expected UserID 42, got %d", uc.UserID)
+		}
+	})
+
+	t.Run("all fail", func(t *testing.T) {
+		chain := NewChainAuthenticator(failStub, failStub)
+		req := httptest.NewRequest("GET", "/", nil)
+
+		_, err := chain.Authenticate(req)
+		if err == nil {
+			t.Fatal("expected error when all authenticators fail")
+		}
+	})
+
+	t.Run("three in chain, first two fail", func(t *testing.T) {
+		chain := NewChainAuthenticator(failStub, failStub, okStub)
+		req := httptest.NewRequest("GET", "/", nil)
+
+		uc, err := chain.Authenticate(req)
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if uc.UserName != "alice" {
+			t.Errorf("expected UserName alice, got %s", uc.UserName)
+		}
+	})
+}
+
+func TestChainAuthenticator_LoginLogout(t *testing.T) {
+	primary := &stubAuthenticator{userCtx: &UserContext{UserID: 1}}
+	secondary := &stubAuthenticator{userCtx: &UserContext{UserID: 2}}
+	chain := NewChainAuthenticator(primary, secondary)
+	ctx := context.Background()
+
+	t.Run("login delegates to primary", func(t *testing.T) {
+		resp, err := chain.Login(ctx, LoginRequest{Username: "u", Password: "p"})
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if resp.Token != "tok" {
+			t.Errorf("expected token from primary, got %s", resp.Token)
+		}
+	})
+
+	t.Run("logout delegates to primary", func(t *testing.T) {
+		if err := chain.Logout(ctx, LogoutRequest{}); err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+	})
+
+	t.Run("login error from primary is returned", func(t *testing.T) {
+		failPrimary := &stubAuthenticator{err: fmt.Errorf("db down")}
+		chain2 := NewChainAuthenticator(failPrimary, secondary)
+		_, err := chain2.Login(ctx, LoginRequest{})
+		if err == nil {
+			t.Fatal("expected error from primary login failure")
+		}
+	})
+}

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

@@ -19,6 +19,7 @@ import (
 type KeyStoreAuthenticator struct {
 	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 == "" {
@@ -70,12 +78,19 @@ type DatabaseAuthenticator struct {
 	cacheTTL  time.Duration
 	sqlNames  *SQLNames
 
+	// Cookie session support (optional, gated by enableCookieSession)
+	enableCookieSession bool
+	cookieOptions       SessionCookieOptions
+
 	// OAuth2 providers registry (multiple providers supported)
 	oauth2Providers      map[string]*OAuth2Provider
 	oauth2ProvidersMutex sync.RWMutex
 
 	// Passkey provider (optional)
 	passkeyProvider PasskeyProvider
+
+	// Optional fallback called when primary authentication fails
+	authenticateCallback func(r *http.Request) (*UserContext, error)
 }
 
 // DatabaseAuthenticatorOptions configures the database authenticator
@@ -93,6 +108,18 @@ type DatabaseAuthenticatorOptions struct {
 	// DBFactory is called to obtain a fresh *sql.DB when the existing connection is closed.
 	// If nil, reconnection is disabled.
 	DBFactory func() (*sql.DB, error)
+	// EnableCookieSession enables cookie-based session management.
+	// When true, Authenticate reads the session token from the cookie named by
+	// CookieOptions.Name (default "session_token") in addition to the Authorization header,
+	// and LoginWithCookie / LogoutWithCookie automatically set / clear the cookie.
+	EnableCookieSession bool
+	// 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 {
@@ -120,6 +147,9 @@ func NewDatabaseAuthenticatorWithOptions(db *sql.DB, opts DatabaseAuthenticatorO
 		cacheTTL:             opts.CacheTTL,
 		sqlNames:             sqlNames,
 		passkeyProvider:      opts.PasskeyProvider,
+		enableCookieSession:  opts.EnableCookieSession,
+		cookieOptions:        opts.CookieOptions,
+		authenticateCallback: opts.AuthenticateCallback,
 	}
 }
 
@@ -159,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)
@@ -265,6 +299,33 @@ func (a *DatabaseAuthenticator) Logout(ctx context.Context, req LogoutRequest) e
 	return nil
 }
 
+// LoginWithCookie performs a login and, when EnableCookieSession is true, writes the
+// session cookie to w using the configured CookieOptions. The LoginResponse is returned
+// regardless of whether cookie sessions are enabled.
+func (a *DatabaseAuthenticator) LoginWithCookie(ctx context.Context, req LoginRequest, w http.ResponseWriter) (*LoginResponse, error) {
+	resp, err := a.Login(ctx, req)
+	if err != nil {
+		return nil, err
+	}
+	if a.enableCookieSession {
+		SetSessionCookie(w, resp, a.cookieOptions)
+	}
+	return resp, nil
+}
+
+// LogoutWithCookie performs a logout and, when EnableCookieSession is true, clears the
+// session cookie on w. The logout itself is performed regardless of the cookie flag.
+func (a *DatabaseAuthenticator) LogoutWithCookie(ctx context.Context, req LogoutRequest, w http.ResponseWriter) error {
+	err := a.Logout(ctx, req)
+	if err != nil {
+		return err
+	}
+	if a.enableCookieSession {
+		ClearSessionCookie(w, a.cookieOptions)
+	}
+	return nil
+}
+
 func (a *DatabaseAuthenticator) Authenticate(r *http.Request) (*UserContext, error) {
 	// Extract session token from header or cookie
 	sessionToken := r.Header.Get("Authorization")
@@ -272,11 +333,12 @@ func (a *DatabaseAuthenticator) Authenticate(r *http.Request) (*UserContext, err
 	var tokens []string
 
 	if sessionToken == "" {
-		// Try cookie
-		if token := GetSessionCookie(r); token != "" {
+		if a.enableCookieSession {
+			if token := GetSessionCookie(r, a.cookieOptions); token != "" {
 				tokens = []string{token}
 				reference = "cookie"
 			}
+		}
 	} else {
 		// Parse Authorization header which may contain multiple comma-separated tokens
 		// Format: "Token abc, Token def" or "Bearer abc" or just "abc"
@@ -295,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")
 	}
 
@@ -357,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
 	}
@@ -583,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)

pkg/server/staticweb/mount.go

@@ -75,11 +75,21 @@ func (m *mountPoint) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 			fallbackPath := m.fallbackStrategy.GetFallbackPath(filePath)
 			file, err = m.provider.Open(strings.TrimPrefix(fallbackPath, "/"))
 			if err == nil {
-				// Successfully opened fallback file
 				defer file.Close()
 				m.serveFile(w, r, fallbackPath, file)
 				return
 			}
+
+			// For extensionless paths, also try path/index.html
+			if path.Ext(filePath) == "" {
+				indexFallback := path.Join(filePath, "index.html")
+				file, err = m.provider.Open(strings.TrimPrefix(indexFallback, "/"))
+				if err == nil {
+					defer file.Close()
+					m.serveFile(w, r, indexFallback, file)
+					return
+				}
+			}
 		}
 
 		// No fallback or fallback failed - return 404

pkg/server/staticweb/policies/fallback.go

@@ -49,9 +49,15 @@ func (f *HTMLFallbackStrategy) GetFallbackPath(filePath string) string {
 	return f.indexFile
 }
 
-// isStaticAsset checks if the path looks like a static asset (has a file extension).
+// isStaticAsset checks if the path looks like a static asset (has a non-HTML file extension).
+// Paths with no extension are not considered static assets so fallback logic can resolve
+// them to path.html or path/index.html.
 func (f *HTMLFallbackStrategy) isStaticAsset(filePath string) bool {
-	return path.Ext(filePath) != ""
+	ext := strings.ToLower(path.Ext(filePath))
+	if ext == "" || ext == ".html" || ext == ".htm" {
+		return false
+	}
+	return true
 }
 
 // ExtensionBasedFallback implements a fallback strategy that skips fallback for known static file extensions.

pkg/websocketspec/handler.go

@@ -3,6 +3,7 @@ package websocketspec
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"net/http"
 	"reflect"
@@ -17,6 +18,17 @@ import (
 	"github.com/bitechdev/ResolveSpec/pkg/reflection"
 )
 
+// newErrorResponseFromErr creates an error response from a Go error, including the SQL
+// query in the error info when the error is a database SQLError.
+func newErrorResponseFromErr(id, code string, err error) *ResponseMessage {
+	resp := NewErrorResponse(id, code, err.Error())
+	var sqlErr *common.SQLError
+	if errors.As(err, &sqlErr) {
+		resp.Error.SQL = sqlErr.SQL
+	}
+	return resp
+}
+
 // Handler handles WebSocket connections and messages
 type Handler struct {
 	db                  common.Database
@@ -236,7 +248,7 @@ func (h *Handler) handleRead(conn *Connection, msg *Message, hookCtx *HookContex
 
 	if err != nil {
 		logger.Error("[WebSocketSpec] Read operation failed: %v", err)
-		errResp := NewErrorResponse(msg.ID, "read_error", err.Error())
+		errResp := newErrorResponseFromErr(msg.ID, "read_error", err)
 		_ = conn.SendJSON(errResp)
 		return
 	}
@@ -272,7 +284,7 @@ func (h *Handler) handleCreate(conn *Connection, msg *Message, hookCtx *HookCont
 	data, err := h.create(hookCtx)
 	if err != nil {
 		logger.Error("[WebSocketSpec] Create operation failed: %v", err)
-		errResp := NewErrorResponse(msg.ID, "create_error", err.Error())
+		errResp := newErrorResponseFromErr(msg.ID, "create_error", err)
 		_ = conn.SendJSON(errResp)
 		return
 	}
@@ -310,7 +322,7 @@ func (h *Handler) handleUpdate(conn *Connection, msg *Message, hookCtx *HookCont
 	data, err := h.update(hookCtx)
 	if err != nil {
 		logger.Error("[WebSocketSpec] Update operation failed: %v", err)
-		errResp := NewErrorResponse(msg.ID, "update_error", err.Error())
+		errResp := newErrorResponseFromErr(msg.ID, "update_error", err)
 		_ = conn.SendJSON(errResp)
 		return
 	}
@@ -348,7 +360,7 @@ func (h *Handler) handleDelete(conn *Connection, msg *Message, hookCtx *HookCont
 	err := h.delete(hookCtx)
 	if err != nil {
 		logger.Error("[WebSocketSpec] Delete operation failed: %v", err)
-		errResp := NewErrorResponse(msg.ID, "delete_error", err.Error())
+		errResp := newErrorResponseFromErr(msg.ID, "delete_error", err)
 		_ = conn.SendJSON(errResp)
 		return
 	}

pkg/websocketspec/message.go

@@ -99,6 +99,9 @@ type ErrorInfo struct {
 
 	// Details contains additional error context
 	Details map[string]interface{} `json:"details,omitempty"`
+
+	// SQL is the query that caused the error, populated for database errors
+	SQL string `json:"sql,omitempty"`
 }
 
 // RequestMessage represents a client request