fix(session): redesign read-only extractor handling — opt-in trust + cached source

Replaces the implicit "preserve query/form/param/custom session IDs" behaviour
with an explicit, validated opt-in and centralizes source tracking so chained
extractors stay consistent across multiple Store.Get calls in the same request.

Changes:

- extractors: add Source.IsWritable() so callers no longer hand-roll the
  cookie/header check.
- session.Store: cache the resolved session ID together with its originating
  Source in request locals (sessionIDInfo). resolveSessionID iterates chain
  sub-extractors and reports the source that actually produced the value;
  subsequent Store.Get calls in the same request reuse that decision instead
  of re-deriving it from the chain wrapper.
- session.Config: add TrustClientSessionID (default false) and
  ClientSessionIDValidator. Read-only sources (query/form/param/custom) only
  preserve a client-supplied unknown ID when both flags are set and the
  validator accepts it; otherwise the ID is discarded and a fresh server ID
  is generated, matching cookie/header fixation protection. Cookie/header
  sources are unaffected and always discard unknown IDs.
- docs/middleware/session.md: document the new flags, the security
  trade-offs, and the recommended HMAC/allow-list validator pattern.
- store_test.go: update Test_Store_resolveSessionID to the new signature,
  cover trust-on/off, validator rejects, opt-in roundtrip, chain source
  resolution, two-Get-same-request consistency for both query and cookie
  sources, and empty client ID. Test_Store_DeleteSession now models the
  cross-request delete + re-Get path instead of relying on the previous
  regenerate-loop bug.

Closes #4234

Author: ReneWerner87

docs/middleware/session.md

@@ -369,6 +369,37 @@ extractors.Chain(
 )
 ```
 
+### Trusting Client-Supplied IDs from Read-Only Sources
+
+By default, an unknown session ID from any source is discarded and a new one is generated via `KeyGenerator`. For cookie/header sources that is also the response channel for the new ID, so the next request continues with it. Read-only sources (query, form, URL param, custom extractors) cannot communicate a new ID back, so the same client request would otherwise create a new orphan session every time.
+
+If your application needs read-only sources to drive a persistent session — for example a non-browser client that always sends the same `?SESSIONID=...` — opt in explicitly:
+
+```go
+app.Use(session.New(session.Config{
+    Extractor:                extractors.FromQuery("SESSIONID"),
+    TrustClientSessionID:     true,
+    ClientSessionIDValidator: func(id string) bool {
+        // Verify the format/origin of the ID. Reject anything you did not issue.
+        // Example: HMAC-signed IDs, length checks, allow-list lookups, ...
+        return isValidSignedID(id)
+    },
+}))
+```
+
+**Security implications.** Trusting client-supplied IDs without validation enables:
+
+- **Session fixation** — an attacker can craft a link such as `?SESSIONID=ATTACKER_KNOWN_VALUE`; once the victim follows it, the server creates a session under that ID and the attacker can hijack it.
+- **Storage poisoning** — any caller can populate your session storage with arbitrary keys.
+
+Mitigations:
+
+1. Always supply a `ClientSessionIDValidator` that rejects IDs you did not issue (HMAC signature, registered allow-list, signed JWT, etc.).
+2. Combine the read-only source with a server-issued token bootstrap step.
+3. Prefer cookie or header extractors whenever the client can store them.
+
+Cookie and header sources are unaffected by this flag — their unknown IDs are always discarded to prevent fixation.
+
 ### Custom Extractors (Session-specific)
 
 Prefer the helper constructors from the extractors module. See the Extractors Guide for the full API; below are session-specific examples and notes.
@@ -681,6 +712,8 @@ extractors.Chain(extractors ...extractors.Extractor) extractors.Extractor
 | `Store`             | `*session.Store`            | Pre-built session store (use when you need to share/register types) | `nil` (auto-created)                       |
 | `Storage`           | `fiber.Storage`             | Session storage backend (used when creating a store if `Store` is nil) | `memory.New()`                             |
 | `Extractor`         | `extractors.Extractor`      | Session ID extraction       | `extractors.FromCookie("session_id")`     |
+| `TrustClientSessionID` | `bool`                   | Accept client-supplied IDs from read-only sources (query/form/param/custom) when no data exists. Requires `ClientSessionIDValidator`. | `false` |
+| `ClientSessionIDValidator` | `func(string) bool` | Validates a client-supplied session ID before persisting it. Required when `TrustClientSessionID` is `true`; `nil` rejects all. | `nil` |
 | `KeyGenerator`      | `func() string`             | Session ID generator        | `utils.SecureToken`                             |
 | `IdleTimeout`       | `time.Duration`             | Inactivity timeout          | `30 * time.Minute`                         |
 | `AbsoluteTimeout`   | `time.Duration`             | Maximum session duration    | `0` (unlimited)                            |

extractors/extractors.go

@@ -60,6 +60,15 @@ const (
 	SourceCustom
 )
 
+// IsWritable reports whether the source allows the server to send a value back
+// to the client in the response (e.g. Set-Cookie, response header). Cookie and
+// header sources are writable; query, form, param, custom and auth-header
+// sources are read-only — the client controls the value on every request and
+// the server cannot rotate it in the response.
+func (s Source) IsWritable() bool {
+	return s == SourceCookie || s == SourceHeader
+}
+
 // ErrNotFound is returned when the requested value is missing or empty.
 var ErrNotFound = errors.New("value not found")
 

middleware/session/config.go

@@ -56,6 +56,36 @@ type Config struct {
 	// Optional. Default: extractors.FromCookie("session_id")
 	Extractor extractors.Extractor
 
+	// TrustClientSessionID controls whether client-supplied session IDs from
+	// read-only sources (query, form, URL param, custom extractor) are accepted
+	// as-is when no session data exists yet for that ID.
+	//
+	// When false (default), unknown IDs from read-only sources are discarded
+	// and the server generates a new ID via KeyGenerator — the same behaviour
+	// already applied to cookie/header sources to prevent session fixation.
+	//
+	// When true, the client-supplied ID is preserved and a fresh session is
+	// stored under it, so subsequent requests carrying the same ID load the
+	// same session. ClientSessionIDValidator must be set in this case;
+	// otherwise the client ID is rejected and a new one is generated.
+	//
+	// SECURITY: Enabling this opens the door to session fixation and storage
+	// poisoning by clients that can choose arbitrary IDs. Use only with a
+	// strong validator (HMAC-signed, length/format-checked, monotonically
+	// issued, etc.) and prefer cookie/header extractors when possible.
+	//
+	// Optional. Default: false
+	TrustClientSessionID bool
+
+	// ClientSessionIDValidator is invoked for client-supplied session IDs from
+	// read-only sources before they are persisted. Return true to accept the
+	// ID, false to reject it (a fresh server-generated ID is used instead).
+	//
+	// Required when TrustClientSessionID is true; nil = reject all.
+	//
+	// Optional. Default: nil
+	ClientSessionIDValidator func(id string) bool
+
 	// IdleTimeout defines the maximum duration of inactivity before the session expires.
 	//
 	// Note: The idle timeout is updated on each `Save()` call. If a middleware handler is used, `Save()` is called automatically.

middleware/session/store.go

@@ -28,6 +28,16 @@ const (
 	sessionIDContextKey sessionIDKey = iota
 )
 
+// sessionIDInfo bundles the resolved session ID with the extractor source that
+// produced it. Both pieces are cached together in the request locals so that a
+// second Store.Get within the same request returns a consistent answer — in
+// particular, chained extractors keep their original source decision instead of
+// being re-derived from the wrapper Extractor.Source.
+type sessionIDInfo struct {
+	id     string
+	source extractors.Source
+}
+
 // Store manages session data using the configured storage backend.
 type Store struct {
 	Config
@@ -124,22 +134,16 @@ func (s *Store) getSession(c fiber.Ctx) (*Session, error) {
 	var rawData []byte
 	var err error
 
-	id, ok := c.Locals(sessionIDContextKey).(string)
-
-	// writableSource tracks whether the session ID came from a writable source
-	// (cookie or header). For writable sources, an unknown ID is discarded and a new
-	// one is generated to prevent session fixation. For read-only sources (query,
-	// form, param, custom), the client-provided ID is preserved so that subsequent
-	// requests using the same query parameter are associated with the same session.
-	var writableSource bool
-	if !ok {
-		id, writableSource = s.getSessionID(c)
-	} else {
-		// ID was cached from a prior call within this request; derive writability
-		// from the primary (first or only) extractor source.
-		src := s.Extractor.Source
-		writableSource = src == extractors.SourceCookie || src == extractors.SourceHeader
+	// Resolve the session ID and the source that produced it. The pair is cached
+	// in the request locals so a second call within the same request returns the
+	// same answer — including for chained extractors where the source is decided
+	// at extraction time and would otherwise be lost.
+	info, alreadyResolved := c.Locals(sessionIDContextKey).(sessionIDInfo)
+	if !alreadyResolved {
+		info = s.resolveSessionID(c)
+		c.Locals(sessionIDContextKey, info)
 	}
+	id := info.id
 
 	fresh := false // Session is not fresh initially; only set to true if we generate a new ID
 
@@ -150,21 +154,22 @@ func (s *Store) getSession(c fiber.Ctx) (*Session, error) {
 			return nil, err
 		}
 		if rawData == nil {
-			if writableSource {
-				// For writable sources (cookie, header), discard the client-provided
-				// ID and generate a new one to prevent session fixation attacks.
-				id = ""
-			} else {
-				// For read-only sources (query, form, param, custom), preserve the
-				// client-provided ID and create a fresh session under it so that
-				// subsequent requests carrying the same ID are served the same session.
-				//
-				// Security note: using a read-only source (e.g. FromQuery) means the
-				// client controls the session ID on every request and the server cannot
-				// rotate it in the response. Callers that require strong session
-				// fixation protection should use a cookie or header extractor instead.
+			switch {
+			case alreadyResolved:
+				// A prior call within this request already committed to this ID.
+				// Keep it so multiple Store.Get calls in the same request observe
+				// the same session.
+				fresh = true
+			case s.acceptClientID(info):
+				// Read-only source with an opt-in trusted client ID — preserve so
+				// that subsequent requests carrying the same ID load the same
+				// session.
 				fresh = true
-				c.Locals(sessionIDContextKey, id)
+			default:
+				// Writable source (cookie/header) with an unknown ID, or
+				// untrusted read-only ID — discard and generate a fresh one to
+				// prevent session fixation and storage poisoning.
+				id = ""
 			}
 		}
 	}
@@ -173,7 +178,9 @@ func (s *Store) getSession(c fiber.Ctx) (*Session, error) {
 	if id == "" {
 		fresh = true // The session is fresh if a new ID is generated
 		id = s.KeyGenerator()
-		c.Locals(sessionIDContextKey, id)
+		// Mark the cached source as cookie so the regenerated ID is treated as
+		// server-issued (writable) on any subsequent call within this request.
+		c.Locals(sessionIDContextKey, sessionIDInfo{id: id, source: extractors.SourceCookie})
 	}
 
 	// Create session object
@@ -212,56 +219,54 @@ func (s *Store) getSession(c fiber.Ctx) (*Session, error) {
 	return sess, nil
 }
 
-// getSessionID returns the session ID using the configured extractor, and whether
-// the extraction source is writable (cookie or header). A writable source means
-// the middleware sets the session ID back in the response (e.g. Set-Cookie), so
-// an unrecognized client-supplied ID should be discarded to prevent session
-// fixation. A non-writable source (query, form, param, custom) is read-only; the
-// client controls the ID on every request, so an unrecognized ID is preserved and
-// a fresh session is stored under it.
-//
-// For chained extractors the function iterates the sub-extractors in order and
-// returns the source of the first one that provides a value.
+// resolveSessionID extracts the session ID from the request and reports the
+// source that produced it. For chained extractors the sub-extractors are tried
+// in order so the source of the first one that yields a value wins; for a
+// single extractor the source on the wrapper is used. When extraction fails the
+// returned ID is empty and the source falls back to the wrapper's source.
 //
 // Parameters:
 //   - c: The Fiber context.
 //
 // Returns:
-//   - string: The session ID.
-//   - bool: true when the source is writable (cookie or header).
-//
-// Usage:
-//
-//	id, writable := store.getSessionID(c)
-func (s *Store) getSessionID(c fiber.Ctx) (string, bool) {
-	isWritable := func(src extractors.Source) bool {
-		return src == extractors.SourceCookie || src == extractors.SourceHeader
-	}
-
+//   - sessionIDInfo: The resolved ID together with its originating source.
+func (s *Store) resolveSessionID(c fiber.Ctx) sessionIDInfo {
 	ext := s.Extractor
 
-	// For chained extractors, try each sub-extractor in order so we can identify
-	// which source actually provided the value.
 	if len(ext.Chain) > 0 {
 		for _, chainExt := range ext.Chain {
 			if chainExt.Extract == nil {
 				continue
 			}
 			v, err := chainExt.Extract(c)
 			if err == nil && v != "" {
-				return v, isWritable(chainExt.Source)
+				return sessionIDInfo{id: v, source: chainExt.Source}
 			}
 		}
-		return "", false
+		return sessionIDInfo{source: ext.Source}
 	}
 
-	// Single extractor.
-	sessionID, err := ext.Extract(c)
+	v, err := ext.Extract(c)
 	if err != nil {
-		// If extraction fails, return empty string to generate a new session
-		return "", false
+		return sessionIDInfo{source: ext.Source}
+	}
+	return sessionIDInfo{id: v, source: ext.Source}
+}
+
+// acceptClientID reports whether a client-supplied session ID from a read-only
+// source should be persisted as-is. Writable sources (cookie/header) are never
+// accepted here — they are subject to fixation protection. For read-only
+// sources the application must explicitly opt in via TrustClientSessionID and
+// supply a ClientSessionIDValidator that accepts the ID; otherwise the ID is
+// rejected and a server-generated one is used.
+func (s *Store) acceptClientID(info sessionIDInfo) bool {
+	if info.id == "" || info.source.IsWritable() {
+		return false
+	}
+	if !s.TrustClientSessionID || s.ClientSessionIDValidator == nil {
+		return false
 	}
-	return sessionID, isWritable(ext.Source)
+	return s.ClientSessionIDValidator(info.id)
 }
 
 // Reset deletes all sessions from the storage.