fix(headers): enhance relation name resolution logic

* Allow resolution for both regular headers and X-Files.
* Introduce join-key-aware resolution for disambiguation.
* Add new function to handle multiple fields pointing to the same type.

LICENSE

@@ -1,3 +1,18 @@
+Project Notice
+
+This project was independently developed.
+
+The contents of this repository were prepared and published outside any time
+allocated to Bitech Systems CC and do not contain, incorporate, disclose,
+or rely upon any proprietary or confidential information, trade secrets,
+protected designs, or other intellectual property of Bitech Systems CC.
+
+No portion of this repository reproduces any Bitech Systems CC-specific
+implementation, design asset, confidential workflow, or non-public technical material.
+
+This notice is provided for clarification only and does not modify the terms of
+the Apache License, Version 2.0.
+
 Apache License
 Version 2.0, January 2004
 http://www.apache.org/licenses/
@@ -32,15 +47,15 @@ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
 
-     (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+   (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
 
-     (b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+   (b) You must cause any modified files to carry prominent notices stating that You changed the files; and
 
-     (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+   (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
 
-     (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+   (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
 
-     You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+   You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
 
 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
 
@@ -56,7 +71,7 @@ END OF TERMS AND CONDITIONS
 
 APPENDIX: How to apply the Apache License to your work.
 
-To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!)  The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
+To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
 
 Copyright 2025 wdevs
 

pkg/common/sql_helpers.go

@@ -168,16 +168,17 @@ func SanitizeWhereClause(where string, tableName string, options ...*RequestOpti
 	}
 
 	// Build a set of allowed table prefixes (main table + preloaded relations)
+	// Keys are stored lowercase for case-insensitive matching
 	allowedPrefixes := make(map[string]bool)
 	if tableName != "" {
-		allowedPrefixes[tableName] = true
+		allowedPrefixes[strings.ToLower(tableName)] = true
 	}
 
 	// Add preload relation names as allowed prefixes
 	if len(options) > 0 && options[0] != nil {
 		for pi := range options[0].Preload {
 			if options[0].Preload[pi].Relation != "" {
-				allowedPrefixes[options[0].Preload[pi].Relation] = true
+				allowedPrefixes[strings.ToLower(options[0].Preload[pi].Relation)] = true
 				logger.Debug("Added preload relation '%s' as allowed table prefix", options[0].Preload[pi].Relation)
 			}
 		}
@@ -185,7 +186,7 @@ func SanitizeWhereClause(where string, tableName string, options ...*RequestOpti
 		// Add join aliases as allowed prefixes
 		for _, alias := range options[0].JoinAliases {
 			if alias != "" {
-				allowedPrefixes[alias] = true
+				allowedPrefixes[strings.ToLower(alias)] = true
 				logger.Debug("Added join alias '%s' as allowed table prefix", alias)
 			}
 		}
@@ -217,8 +218,8 @@ func SanitizeWhereClause(where string, tableName string, options ...*RequestOpti
 			currentPrefix, columnName := extractTableAndColumn(condToCheck)
 
 			if currentPrefix != "" && columnName != "" {
-				// Check if the prefix is allowed (main table or preload relation)
-				if !allowedPrefixes[currentPrefix] {
+				// Check if the prefix is allowed (main table or preload relation) - case-insensitive
+				if !allowedPrefixes[strings.ToLower(currentPrefix)] {
 					// Prefix is not in the allowed list - only fix if it's a valid column in the main table
 					if validColumns == nil || isValidColumn(columnName, validColumns) {
 						// Replace the incorrect prefix with the correct main table name

pkg/resolvespec/cursor.go

@@ -32,7 +32,8 @@ func GetCursorFilter(
 	modelColumns []string,
 	options common.RequestOptions,
 ) (string, error) {
-	// Remove schema prefix if present
+	// Separate schema prefix from bare table name
+	fullTableName := tableName
 	if strings.Contains(tableName, ".") {
 		tableName = strings.SplitN(tableName, ".", 2)[1]
 	}
@@ -115,7 +116,7 @@ func GetCursorFilter(
   WHERE cursor_select.%s = %s
     AND (%s)
 )`,
-		tableName,
+		fullTableName,
 		pkName,
 		cursorID,
 		orSQL,

pkg/resolvespec/cursor_test.go

@@ -175,9 +175,9 @@ func TestGetCursorFilter_WithSchemaPrefix(t *testing.T) {
 		t.Fatalf("GetCursorFilter failed: %v", err)
 	}
 
-	// Should handle schema prefix properly
-	if !strings.Contains(filter, "users") {
-		t.Errorf("Filter should reference table name users, got: %s", filter)
+	// Should include full schema-qualified name in FROM clause
+	if !strings.Contains(filter, "public.users") {
+		t.Errorf("Filter FROM clause should use schema-qualified name public.users, got: %s", filter)
 	}
 
 	t.Logf("Generated cursor filter with schema: %s", filter)

pkg/resolvespec/handler.go

@@ -329,6 +329,11 @@ func (h *Handler) handleRead(ctx context.Context, w common.ResponseWriter, id st
 		// Extract model columns for validation
 		modelColumns := reflection.GetModelColumns(model)
 
+		// Default sort to primary key when none provided
+		if len(options.Sort) == 0 {
+			options.Sort = []common.SortOption{{Column: pkName, Direction: "ASC"}}
+		}
+
 		// Get cursor filter SQL
 		cursorFilter, err := GetCursorFilter(tableName, pkName, modelColumns, options)
 		if err != nil {
@@ -1521,22 +1526,22 @@ func (h *Handler) buildFilterCondition(filter common.FilterOption) (conditionStr
 	var args []interface{}
 
 	switch filter.Operator {
-	case "eq":
+	case "eq", "=":
 		condition = fmt.Sprintf("%s = ?", filter.Column)
 		args = []interface{}{filter.Value}
-	case "neq":
+	case "neq", "!=", "<>":
 		condition = fmt.Sprintf("%s != ?", filter.Column)
 		args = []interface{}{filter.Value}
-	case "gt":
+	case "gt", ">":
 		condition = fmt.Sprintf("%s > ?", filter.Column)
 		args = []interface{}{filter.Value}
-	case "gte":
+	case "gte", ">=":
 		condition = fmt.Sprintf("%s >= ?", filter.Column)
 		args = []interface{}{filter.Value}
-	case "lt":
+	case "lt", "<":
 		condition = fmt.Sprintf("%s < ?", filter.Column)
 		args = []interface{}{filter.Value}
-	case "lte":
+	case "lte", "<=":
 		condition = fmt.Sprintf("%s <= ?", filter.Column)
 		args = []interface{}{filter.Value}
 	case "like":
@@ -1565,22 +1570,22 @@ func (h *Handler) applyFilter(query common.SelectQuery, filter common.FilterOpti
 	var args []interface{}
 
 	switch filter.Operator {
-	case "eq":
+	case "eq", "=":
 		condition = fmt.Sprintf("%s = ?", filter.Column)
 		args = []interface{}{filter.Value}
-	case "neq":
+	case "neq", "!=", "<>":
 		condition = fmt.Sprintf("%s != ?", filter.Column)
 		args = []interface{}{filter.Value}
-	case "gt":
+	case "gt", ">":
 		condition = fmt.Sprintf("%s > ?", filter.Column)
 		args = []interface{}{filter.Value}
-	case "gte":
+	case "gte", ">=":
 		condition = fmt.Sprintf("%s >= ?", filter.Column)
 		args = []interface{}{filter.Value}
-	case "lt":
+	case "lt", "<":
 		condition = fmt.Sprintf("%s < ?", filter.Column)
 		args = []interface{}{filter.Value}
-	case "lte":
+	case "lte", "<=":
 		condition = fmt.Sprintf("%s <= ?", filter.Column)
 		args = []interface{}{filter.Value}
 	case "like":

pkg/restheadspec/cursor.go

@@ -32,6 +32,8 @@ func (opts *ExtendedRequestOptions) GetCursorFilter(
 	modelColumns []string, // optional: for validation
 	expandJoins map[string]string, // optional: alias → JOIN SQL
 ) (string, error) {
+	// Separate schema prefix from bare table name
+	fullTableName := tableName
 	if strings.Contains(tableName, ".") {
 		tableName = strings.SplitN(tableName, ".", 2)[1]
 	}
@@ -127,7 +129,7 @@ func (opts *ExtendedRequestOptions) GetCursorFilter(
   WHERE cursor_select.%s = %s
     AND (%s)
 )`,
-		tableName,
+		fullTableName,
 		joinSQL,
 		pkName,
 		cursorID,

pkg/restheadspec/cursor_test.go

@@ -187,9 +187,9 @@ func TestGetCursorFilter_WithSchemaPrefix(t *testing.T) {
 		t.Fatalf("GetCursorFilter failed: %v", err)
 	}
 
-	// Should handle schema prefix properly
-	if !strings.Contains(filter, "users") {
-		t.Errorf("Filter should reference table name users, got: %s", filter)
+	// Should include full schema-qualified name in FROM clause
+	if !strings.Contains(filter, "public.users") {
+		t.Errorf("Filter FROM clause should use schema-qualified name public.users, got: %s", filter)
 	}
 
 	t.Logf("Generated cursor filter with schema: %s", filter)

pkg/restheadspec/handler.go

@@ -731,6 +731,11 @@ func (h *Handler) handleRead(ctx context.Context, w common.ResponseWriter, id st
 			// For now, pass empty map as joins are handled via Preload
 		}
 
+		// Default sort to primary key when none provided
+		if len(options.Sort) == 0 {
+			options.Sort = []common.SortOption{{Column: pkName, Direction: "ASC"}}
+		}
+
 		// Get cursor filter SQL
 		cursorFilter, err := options.GetCursorFilter(tableName, pkName, modelColumns, expandJoins)
 		if err != nil {
@@ -2226,17 +2231,17 @@ func (h *Handler) applyOrFilterGroup(query common.SelectQuery, filters []*common
 // buildFilterCondition builds a single filter condition and returns the condition string and args
 func (h *Handler) buildFilterCondition(qualifiedColumn string, filter *common.FilterOption, tableName string) (filterStr string, filterInterface []interface{}) {
 	switch strings.ToLower(filter.Operator) {
-	case "eq", "equals":
+	case "eq", "equals", "=":
 		return fmt.Sprintf("%s = ?", qualifiedColumn), []interface{}{filter.Value}
-	case "neq", "not_equals", "ne":
+	case "neq", "not_equals", "ne", "!=", "<>":
 		return fmt.Sprintf("%s != ?", qualifiedColumn), []interface{}{filter.Value}
-	case "gt", "greater_than":
+	case "gt", "greater_than", ">":
 		return fmt.Sprintf("%s > ?", qualifiedColumn), []interface{}{filter.Value}
-	case "gte", "greater_than_equals", "ge":
+	case "gte", "greater_than_equals", "ge", ">=":
 		return fmt.Sprintf("%s >= ?", qualifiedColumn), []interface{}{filter.Value}
-	case "lt", "less_than":
+	case "lt", "less_than", "<":
 		return fmt.Sprintf("%s < ?", qualifiedColumn), []interface{}{filter.Value}
-	case "lte", "less_than_equals", "le":
+	case "lte", "less_than_equals", "le", "<=":
 		return fmt.Sprintf("%s <= ?", qualifiedColumn), []interface{}{filter.Value}
 	case "like":
 		return fmt.Sprintf("%s LIKE ?", qualifiedColumn), []interface{}{filter.Value}
@@ -2879,6 +2884,8 @@ func (h *Handler) filterExtendedOptions(validator *common.ColumnValidator, optio
 
 	// Filter base RequestOptions
 	filtered.RequestOptions = validator.FilterRequestOptions(options.RequestOptions)
+	// Restore JoinAliases cleared by FilterRequestOptions — still needed for SanitizeWhereClause
+	filtered.RequestOptions.JoinAliases = options.JoinAliases
 
 	// Filter SearchColumns
 	filtered.SearchColumns = validator.FilterValidColumns(options.SearchColumns)

pkg/restheadspec/headers.go

@@ -274,9 +274,11 @@ func (h *Handler) parseOptionsFromHeaders(r common.Request, model interface{}) E
 		}
 	}
 
-	// Resolve relation names (convert table names to field names) if model is provided
-	// Skip resolution if X-Files header was provided, as XFiles uses Prefix which already contains the correct field names
-	if model != nil && !options.XFilesPresent {
+	// Resolve relation names (convert table names/prefixes to actual model field names) if model is provided.
+	// This runs for both regular headers and X-Files, because XFile prefixes don't always match model
+	// field names (e.g., prefix "HUB" vs field "HUB_RID_HUB"). RelatedKey/ForeignKey are used to
+	// disambiguate when multiple fields point to the same related type.
+	if model != nil {
 		h.resolveRelationNamesInOptions(&options, model)
 	}
 
@@ -863,8 +865,21 @@ func (h *Handler) resolveRelationNamesInOptions(options *ExtendedRequestOptions,
 
 		// Resolve each part of the path
 		currentModel := model
-		for _, part := range parts {
-			resolvedPart := h.resolveRelationName(currentModel, part)
+		for partIdx, part := range parts {
+			isLast := partIdx == len(parts)-1
+			var resolvedPart string
+			if isLast {
+				// For the final part, use join-key-aware resolution to disambiguate when
+				// multiple fields point to the same type (e.g., HUB_RID_HUB vs HUB_RID_ASSIGNEDTO).
+				// RelatedKey = parent's local column linking to child; ForeignKey = local column linking to parent.
+				localKey := preload.RelatedKey
+				if localKey == "" {
+					localKey = preload.ForeignKey
+				}
+				resolvedPart = h.resolveRelationNameWithJoinKey(currentModel, part, localKey)
+			} else {
+				resolvedPart = h.resolveRelationName(currentModel, part)
+			}
 			resolvedParts = append(resolvedParts, resolvedPart)
 
 			// Try to get the model type for the next level
@@ -980,6 +995,101 @@ func (h *Handler) resolveRelationName(model interface{}, nameOrTable string) str
 	return nameOrTable
 }
 
+// resolveRelationNameWithJoinKey resolves a relation name like resolveRelationName, but when
+// multiple fields point to the same related type, uses localKey to pick the one whose bun join
+// tag starts with "join:localKey=". Falls back to resolveRelationName if no key match is found.
+func (h *Handler) resolveRelationNameWithJoinKey(model interface{}, nameOrTable string, localKey string) string {
+	if localKey == "" {
+		return h.resolveRelationName(model, nameOrTable)
+	}
+
+	modelType := reflect.TypeOf(model)
+	if modelType == nil {
+		return nameOrTable
+	}
+	if modelType.Kind() == reflect.Ptr {
+		modelType = modelType.Elem()
+	}
+	if modelType == nil || modelType.Kind() != reflect.Struct {
+		return nameOrTable
+	}
+
+	// If it's already a direct field name, return as-is (no ambiguity).
+	for i := 0; i < modelType.NumField(); i++ {
+		if modelType.Field(i).Name == nameOrTable {
+			return nameOrTable
+		}
+	}
+
+	normalizedInput := strings.ToLower(strings.ReplaceAll(nameOrTable, "_", ""))
+	localKeyLower := strings.ToLower(localKey)
+
+	// Find all fields whose related type matches nameOrTable, then pick the one
+	// whose bun join tag local key matches localKey.
+	var fallbackField string
+	for i := 0; i < modelType.NumField(); i++ {
+		field := modelType.Field(i)
+		fieldType := field.Type
+
+		var targetType reflect.Type
+		if fieldType.Kind() == reflect.Slice {
+			targetType = fieldType.Elem()
+		} else if fieldType.Kind() == reflect.Ptr {
+			targetType = fieldType.Elem()
+		}
+		if targetType != nil && targetType.Kind() == reflect.Ptr {
+			targetType = targetType.Elem()
+		}
+		if targetType == nil || targetType.Kind() != reflect.Struct {
+			continue
+		}
+
+		normalizedTypeName := strings.ToLower(targetType.Name())
+		normalizedTypeName = strings.TrimPrefix(normalizedTypeName, "modelcore")
+		normalizedTypeName = strings.TrimPrefix(normalizedTypeName, "model")
+		if normalizedTypeName != normalizedInput {
+			continue
+		}
+
+		// Type name matches; record as fallback.
+		if fallbackField == "" {
+			fallbackField = field.Name
+		}
+
+		// Check bun join tag: "join:localKey=foreignKey"
+		bunTag := field.Tag.Get("bun")
+		for _, tagPart := range strings.Split(bunTag, ",") {
+			tagPart = strings.TrimSpace(tagPart)
+			if !strings.HasPrefix(tagPart, "join:") {
+				continue
+			}
+			joinSpec := strings.TrimPrefix(tagPart, "join:")
+			// joinSpec can be "col1=col2" or "col1=col2 col3=col4" (multi-col joins)
+			joinCols := strings.Fields(joinSpec)
+			if len(joinCols) == 0 {
+				joinCols = []string{joinSpec}
+			}
+			for _, joinCol := range joinCols {
+				eqIdx := strings.Index(joinCol, "=")
+				if eqIdx < 0 {
+					continue
+				}
+				joinLocalKey := strings.ToLower(joinCol[:eqIdx])
+				if joinLocalKey == localKeyLower {
+					logger.Debug("Resolved '%s' (localKey: %s) -> field '%s'", nameOrTable, localKey, field.Name)
+					return field.Name
+				}
+			}
+		}
+	}
+
+	if fallbackField != "" {
+		logger.Debug("No join key match for '%s' (localKey: %s), using first type match: '%s'", nameOrTable, localKey, fallbackField)
+		return fallbackField
+	}
+	return h.resolveRelationName(model, nameOrTable)
+}
+
 // addXFilesPreload converts an XFiles relation into a PreloadOption
 // and recursively processes its children
 func (h *Handler) addXFilesPreload(xfile *XFiles, options *ExtendedRequestOptions, basePath string) {
@@ -1061,15 +1171,42 @@ func (h *Handler) addXFilesPreload(xfile *XFiles, options *ExtendedRequestOption
 		}
 	}
 
+	// Transfer SqlJoins from XFiles to PreloadOption first, so aliases are available for WHERE sanitization
+	if len(xfile.SqlJoins) > 0 {
+		preloadOpt.SqlJoins = make([]string, 0, len(xfile.SqlJoins))
+		preloadOpt.JoinAliases = make([]string, 0, len(xfile.SqlJoins))
+
+		for _, joinClause := range xfile.SqlJoins {
+			// Sanitize the join clause
+			sanitizedJoin := common.SanitizeWhereClause(joinClause, "", nil)
+			if sanitizedJoin == "" {
+				logger.Warn("X-Files: SqlJoin failed sanitization for %s: %s", relationPath, joinClause)
+				continue
+			}
+
+			preloadOpt.SqlJoins = append(preloadOpt.SqlJoins, sanitizedJoin)
+
+			// Extract join alias for validation
+			alias := extractJoinAlias(sanitizedJoin)
+			if alias != "" {
+				preloadOpt.JoinAliases = append(preloadOpt.JoinAliases, alias)
+				logger.Debug("X-Files: Extracted join alias for %s: %s", relationPath, alias)
+			}
+		}
+
+		logger.Debug("X-Files: Added %d SQL joins to preload %s", len(preloadOpt.SqlJoins), relationPath)
+	}
+
 	// Add WHERE clause if SQL conditions specified
+	// SqlJoins must be processed first so join aliases are known and not incorrectly replaced
 	whereConditions := make([]string, 0)
 	if len(xfile.SqlAnd) > 0 {
-		// Process each SQL condition
-		// Note: We don't add table prefixes here because they're only needed for JOINs
-		// The handler will add prefixes later if SqlJoins are present
+		var sqlAndOpts *common.RequestOptions
+		if len(preloadOpt.JoinAliases) > 0 {
+			sqlAndOpts = &common.RequestOptions{JoinAliases: preloadOpt.JoinAliases}
+		}
 		for _, sqlCond := range xfile.SqlAnd {
-			// Sanitize the condition without adding prefixes
-			sanitizedCond := common.SanitizeWhereClause(sqlCond, xfile.TableName)
+			sanitizedCond := common.SanitizeWhereClause(sqlCond, xfile.TableName, sqlAndOpts)
 			if sanitizedCond != "" {
 				whereConditions = append(whereConditions, sanitizedCond)
 			}
@@ -1114,32 +1251,6 @@ func (h *Handler) addXFilesPreload(xfile *XFiles, options *ExtendedRequestOption
 		logger.Debug("X-Files: Set foreign key for %s: %s", relationPath, xfile.ForeignKey)
 	}
 
-	// Transfer SqlJoins from XFiles to PreloadOption
-	if len(xfile.SqlJoins) > 0 {
-		preloadOpt.SqlJoins = make([]string, 0, len(xfile.SqlJoins))
-		preloadOpt.JoinAliases = make([]string, 0, len(xfile.SqlJoins))
-
-		for _, joinClause := range xfile.SqlJoins {
-			// Sanitize the join clause
-			sanitizedJoin := common.SanitizeWhereClause(joinClause, "", nil)
-			if sanitizedJoin == "" {
-				logger.Warn("X-Files: SqlJoin failed sanitization for %s: %s", relationPath, joinClause)
-				continue
-			}
-
-			preloadOpt.SqlJoins = append(preloadOpt.SqlJoins, sanitizedJoin)
-
-			// Extract join alias for validation
-			alias := extractJoinAlias(sanitizedJoin)
-			if alias != "" {
-				preloadOpt.JoinAliases = append(preloadOpt.JoinAliases, alias)
-				logger.Debug("X-Files: Extracted join alias for %s: %s", relationPath, alias)
-			}
-		}
-
-		logger.Debug("X-Files: Added %d SQL joins to preload %s", len(preloadOpt.SqlJoins), relationPath)
-	}
-
 	// Check if this table has a recursive child - if so, mark THIS preload as recursive
 	// and store the recursive child's RelatedKey for recursion generation
 	hasRecursiveChild := false

pkg/security/middleware.go

@@ -456,6 +456,125 @@ func GetUserMeta(ctx context.Context) (map[string]any, bool) {
 	return meta, ok
 }
 
+// SessionCookieOptions configures the session cookie set by SetSessionCookie.
+// All fields are optional; sensible secure defaults are applied when omitted.
+type SessionCookieOptions struct {
+	// Name is the cookie name. Defaults to "session_token".
+	Name string
+	// Path is the cookie path. Defaults to "/".
+	Path string
+	// Domain restricts the cookie to a specific domain. Empty means current host.
+	Domain string
+	// Secure sets the Secure flag. Defaults to true.
+	// Set to false only in local development over HTTP.
+	Secure *bool
+	// SameSite sets the SameSite policy. Defaults to http.SameSiteLaxMode.
+	SameSite http.SameSite
+}
+
+func (o SessionCookieOptions) name() string {
+	if o.Name != "" {
+		return o.Name
+	}
+	return "session_token"
+}
+
+func (o SessionCookieOptions) path() string {
+	if o.Path != "" {
+		return o.Path
+	}
+	return "/"
+}
+
+func (o SessionCookieOptions) secure() bool {
+	if o.Secure != nil {
+		return *o.Secure
+	}
+	return true
+}
+
+func (o SessionCookieOptions) sameSite() http.SameSite {
+	if o.SameSite != 0 {
+		return o.SameSite
+	}
+	return http.SameSiteLaxMode
+}
+
+// SetSessionCookie writes the session_token cookie to the response after a successful login.
+// Call this immediately after a successful Authenticator.Login() call.
+//
+// Example:
+//
+//	resp, err := auth.Login(r.Context(), req)
+//	if err != nil { ... }
+//	security.SetSessionCookie(w, resp)
+//	json.NewEncoder(w).Encode(resp)
+func SetSessionCookie(w http.ResponseWriter, loginResp *LoginResponse, opts ...SessionCookieOptions) {
+	var o SessionCookieOptions
+	if len(opts) > 0 {
+		o = opts[0]
+	}
+
+	maxAge := 0
+	if loginResp.ExpiresIn > 0 {
+		maxAge = int(loginResp.ExpiresIn)
+	}
+
+	http.SetCookie(w, &http.Cookie{
+		Name:     o.name(),
+		Value:    loginResp.Token,
+		Path:     o.path(),
+		Domain:   o.Domain,
+		MaxAge:   maxAge,
+		HttpOnly: true,
+		Secure:   o.secure(),
+		SameSite: o.sameSite(),
+	})
+}
+
+// GetSessionCookie returns the session token value from the request cookie, or empty string if not present.
+//
+// Example:
+//
+//	token := security.GetSessionCookie(r)
+func GetSessionCookie(r *http.Request, opts ...SessionCookieOptions) string {
+	var o SessionCookieOptions
+	if len(opts) > 0 {
+		o = opts[0]
+	}
+	cookie, err := r.Cookie(o.name())
+	if err != nil {
+		return ""
+	}
+	return cookie.Value
+}
+
+// ClearSessionCookie expires the session_token cookie, effectively logging the user out on the browser side.
+// Call this after a successful Authenticator.Logout() call.
+//
+// Example:
+//
+//	err := auth.Logout(r.Context(), req)
+//	if err != nil { ... }
+//	security.ClearSessionCookie(w)
+func ClearSessionCookie(w http.ResponseWriter, opts ...SessionCookieOptions) {
+	var o SessionCookieOptions
+	if len(opts) > 0 {
+		o = opts[0]
+	}
+
+	http.SetCookie(w, &http.Cookie{
+		Name:     o.name(),
+		Value:    "",
+		Path:     o.path(),
+		Domain:   o.Domain,
+		MaxAge:   -1,
+		HttpOnly: true,
+		Secure:   o.secure(),
+		SameSite: o.sameSite(),
+	})
+}
+
 // GetModelRulesFromContext extracts ModelRules stored by NewModelAuthMiddleware
 func GetModelRulesFromContext(ctx context.Context) (modelregistry.ModelRules, bool) {
 	rules, ok := ctx.Value(ModelRulesKey).(modelregistry.ModelRules)

pkg/security/providers.go

@@ -222,9 +222,8 @@ func (a *DatabaseAuthenticator) Authenticate(r *http.Request) (*UserContext, err
 
 	if sessionToken == "" {
 		// Try cookie
-		cookie, err := r.Cookie("session_token")
-		if err == nil {
-			tokens = []string{cookie.Value}
+		if token := GetSessionCookie(r); token != "" {
+			tokens = []string{token}
 			reference = "cookie"
 		}
 	} else {

pkg/server/staticweb/providers/embed.go

@@ -98,6 +98,7 @@ func (p *EmbedFSProvider) Open(name string) (fs.File, error) {
 
 	// Apply prefix stripping by prepending the prefix to the requested path
 	actualPath := name
+	alternatePath := ""
 	if p.stripPrefix != "" {
 		// Clean the paths to handle leading/trailing slashes
 		prefix := strings.Trim(p.stripPrefix, "/")
@@ -105,12 +106,25 @@ func (p *EmbedFSProvider) Open(name string) (fs.File, error) {
 
 		if prefix != "" {
 			actualPath = path.Join(prefix, cleanName)
+			alternatePath = cleanName
 		} else {
 			actualPath = cleanName
 		}
 	}
+	// First try the actual path with prefix
+	if file, err := p.fs.Open(actualPath); err == nil {
+		return file, nil
+	}
 
-	return p.fs.Open(actualPath)
+	// If alternate path is different, try it as well
+	if alternatePath != "" && alternatePath != actualPath {
+		if file, err := p.fs.Open(alternatePath); err == nil {
+			return file, nil
+		}
+	}
+
+	// If both attempts fail, return the error from the first attempt
+	return nil, fmt.Errorf("file not found: %s", name)
 }
 
 // Close releases any resources held by the provider.

pkg/server/staticweb/providers/local.go

@@ -53,6 +53,7 @@ func (p *LocalFSProvider) Open(name string) (fs.File, error) {
 
 	// Apply prefix stripping by prepending the prefix to the requested path
 	actualPath := name
+	alternatePath := ""
 	if p.stripPrefix != "" {
 		// Clean the paths to handle leading/trailing slashes
 		prefix := strings.Trim(p.stripPrefix, "/")
@@ -60,12 +61,26 @@ func (p *LocalFSProvider) Open(name string) (fs.File, error) {
 
 		if prefix != "" {
 			actualPath = path.Join(prefix, cleanName)
+			alternatePath = cleanName
 		} else {
 			actualPath = cleanName
 		}
 	}
 
-	return p.fs.Open(actualPath)
+	// First try the actual path with prefix
+	if file, err := p.fs.Open(actualPath); err == nil {
+		return file, nil
+	}
+
+	// If alternate path is different, try it as well
+	if alternatePath != "" && alternatePath != actualPath {
+		if file, err := p.fs.Open(alternatePath); err == nil {
+			return file, nil
+		}
+	}
+
+	// If both attempts fail, return the error from the first attempt
+	return nil, fmt.Errorf("file not found: %s", name)
 }
 
 // Close releases any resources held by the provider.

pkg/server/staticweb/providers/zip.go

@@ -56,6 +56,7 @@ func (p *ZipFSProvider) Open(name string) (fs.File, error) {
 
 	// Apply prefix stripping by prepending the prefix to the requested path
 	actualPath := name
+	alternatePath := ""
 	if p.stripPrefix != "" {
 		// Clean the paths to handle leading/trailing slashes
 		prefix := strings.Trim(p.stripPrefix, "/")
@@ -63,12 +64,26 @@ func (p *ZipFSProvider) Open(name string) (fs.File, error) {
 
 		if prefix != "" {
 			actualPath = path.Join(prefix, cleanName)
+			alternatePath = cleanName
 		} else {
 			actualPath = cleanName
 		}
 	}
 
-	return p.zipFS.Open(actualPath)
+	// First try the actual path with prefix
+	if file, err := p.zipFS.Open(actualPath); err == nil {
+		return file, nil
+	}
+
+	// If alternate path is different, try it as well
+	if alternatePath != "" && alternatePath != actualPath {
+		if file, err := p.zipFS.Open(alternatePath); err == nil {
+			return file, nil
+		}
+	}
+
+	// If both attempts fail, return the error from the first attempt
+	return nil, fmt.Errorf("file not found: %s", name)
 }
 
 // Close releases resources held by the zip reader.