0.4.0: explicit login()/logout() that always rotate the session ID, and __Host- cookie by default

[allen0099]

Follow-up to #225 / #255. #255 adds an opt-in rotate_session_id(request) for 0.3.8. A helper the developer has to remember is the weakest form of the fixation defence, and some of the stronger forms are breaking changes, so this collects them for 0.4.0.

Principle

Becoming authenticated happens through one explicit API, and that API always issues a new session ID. There is no other way to attach a user through the library, so the library's own identity (session.user, get_session, UserSessionDep) cannot be fixated.

Limit: an application that decides "logged in" from its own request.session keys (request.session.get("user_id"), the usual Starlette pattern) is outside what the library can see. The docs must say this up front: use the library's identity, or rotate yourself.

Proposal

1. Explicit login() / logout()
   • await login(request, user) (exact shape to be decided: request-level function, or a method on the request's session) attaches the user and always rotates the ID. The middleware sends the new token through the request's transport.
   • logout() deletes the record. request.session.clear() keeps meaning logout, for compatibility.
   • Session.user becomes read-only outside these calls. Code that sets it directly today breaks: this is the breaking part.
   • rotate_session_id() stays for privilege changes without a new user (or becomes elevate()).
2. A login starts a new session instead of promoting the anonymous one
   • login() creates a fresh record, copies only the data the caller asks to keep (keep=["cart"], or all by default: to be decided), and deletes the old one.
   • Nothing an attacker put into a planted session is carried into the authenticated one unless the application chose to keep it.
3. Short grace period after rotation
   • For a few seconds the old ID resolves to the new session (a small redirect record, not the old data), so concurrent in-flight requests that still carry the old token do not fail.
   • This makes rotation cheap enough to use freely. It has to be designed together with 0.4.0: conditional session writes so a stale request cannot restore a deleted session #128, so that a stale write cannot bring the old record back.
4. Cookies that are hard to plant, by default
   • Default cookie_name becomes __Host-session with Secure. Browsers refuse __Host- cookies set from a subdomain or with a Domain attribute, which removes the usual fixation vector.
   • Local development over plain http needs an explicit opt-out, and SessionConfig should reject contradictory settings (a __Host- name with cookie_domain, a path other than /, or no Secure).
   • Changing the default name logs every existing user out once; the changelog must say so.

Optional, can be split out:

• Store a hash of the session ID in the backend instead of the ID itself, so a leaked store does not yield usable tokens.
• Per-user epoch revocation (Session: revoke all of a user's sessions without scanning the keyspace #246).

Differences from Starlette's SessionMiddleware after this change

The dict API stays compatible: request.session still reads and writes the same way. What changes is the login semantics: writing a key no longer means "logged in" as far as the library is concerned. The migration guide needs a short table:

• where data lives;
• login and logout;
• revocation;
• cookie defaults;
• size limit;
• the need for a backend.

Related 0.4.0 items to ship together

• 0.4.0: remove the deprecated SessionMiddleware #69 removes the deprecated SessionMiddleware.
• 0.4.0: make UserSessionDep require a session with a user #127 makes UserSessionDep require a user, which fits login() being the only way to get one.
• 0.4.0: conditional session writes so a stale request cannot restore a deleted session #128 conditional session writes, needed for the grace period.

One migration section in the docs covering all of them is easier on users than several separate ones.

[allen0099]

Decisions (2026-09-29)

Already in 0.3.9: login(request, user) as a request-level function, and the FutureWarning for the __Host-session / Secure cookie defaults (part 4).

Scope for 0.4.0

1. logout()
   • Add await logout(request), mirroring login(): it deletes the session record, and a cookie client gets its cookie expired.
   • request.session.clear() keeps meaning logout, and the two are equivalent.
2. Session.user becomes read-only outside login() and SessionManager.create_session(user=...).
   • This is the breaking part.
   • Code that assigns session.user directly breaks. Under the middleware it moves to login(); header-only API clients without the middleware move to create_session(user=...).
3. rotate_session_id() keeps its name. It has been public since 0.3.8, so a rename (elevate()) would only add another deprecation.
4. Data carried into the logged-in session
   • All data is carried by default, so "the cart survives login" keeps working.
   • An optional keep= argument narrows it: keep=["cart"] keeps only the cart, keep=[] keeps nothing.
   • The ID rotation already makes a planted token worthless, and the __Host- default removes the usual way to plant one. keep= is additive, so it can slip to 0.4.x if needed.
5. No grace period for login() or a privilege change. The old ID is exactly the one an attacker may have planted: a grace period would let it resolve to the victim's authenticated session for those seconds. It keeps being invalidated immediately.

Split out

• Grace period for periodic rotation: Session: periodic ID rotation with a grace period for in-flight requests #375. It is only needed if the library ever rotates without suspecting the old token, and it is not in 0.4.0.
• Storing a hash of the session ID in the backend: Session: store a hash of the session ID in the backend #374.
• Revoking every session of a user: Session: revoke all of a user's sessions without scanning the keyspace #246, which stays independent of this issue.

The migration guide's "not decided yet" points for this issue (what login() carries over, the logout API) are updated with the decisions above.