Skip to content

feat(session)!: default the session cookie to __Host-session with Secure - #415

Merged
allen0099 merged 1 commit into
masterfrom
feat/256-host-cookie-default
Sep 30, 2026
Merged

allen0099 merged 1 commit into
masterfrom
feat/256-host-cookie-default

Conversation

@allen0099

Copy link
Copy Markdown
Owner

Part of #256 (part 4 of the proposal: cookie defaults). logout(), read-only Session.user and keep= follow in a separate PR, so this one does not close the issue.

Changes

  • SessionConfig.cookie_name defaults to "__Host-session" and cookie_https_only to True.
  • A cookie browsers would refuse now raises a ValidationError instead of the 0.3.9 UserWarning:
    • a __Host- name without Secure, with a cookie_path other than "/" or with a cookie_domain;
    • a __Secure- name without Secure.
  • Because the default name is __Host-session, setting only cookie_https_only=False, cookie_path or cookie_domain also raises. The message:
    • marks the name as (the default);
    • suggests cookie_name='session', cookie_https_only=False for plain HTTP;
    • suggests cookie_name='__Secure-session' for a path or domain, so the Secure flag is kept;
    • links to the docs.
  • The SameSite=None warning no longer fires for a prefixed name, which the prefix check already rejects.
  • The middleware's 0.3.9 FutureWarning about the cookie defaults is removed.
  • Docs, in both languages:
    • SESSION.md: the "Cookie defaults" section, the config reference, and the HTTPS-only section.
    • MIGRATING_0_4.md#session-cookie: the default-name case, and the note that 0.3.9 warned about it only under the middleware.
  • Examples: the plain-HTTP examples keep their explicit cookie settings with updated comments; the HTTPS ones drop them.

Tests

SessionConfig.cookie_name defaults to "__Host-session" and
cookie_https_only to True. Browsers accept a __Host- cookie only when it
is Secure, has Path=/ and no Domain, and never from a subdomain, which
removes the usual way to plant a session cookie.

A __Host- name without Secure, with a cookie_path other than "/" or with
a cookie_domain, and a __Secure- name without Secure, now raise a
ValidationError instead of the 0.3.9 UserWarning. The message says when
the name is the default and suggests a fix that fits the problem. The
SameSite=None warning no longer fires for a prefixed name, which the
prefix check already rejects. The middleware's FutureWarning about the
cookie defaults is removed.

BREAKING CHANGE: the session cookie is renamed to __Host-session and is
Secure by default, so every cookie session is logged out once after the
upgrade and the cookie is not sent over plain HTTP. For plain-HTTP
development, set cookie_name="session", cookie_https_only=False. Setting
only cookie_https_only=False, cookie_path or cookie_domain with the
default name now raises.

Refs #256
@allen0099 allen0099 added this to the 0.4.0 milestone Sep 30, 2026
@allen0099 allen0099 added enhancement New feature or request session Session management subsystem breaking-change Changes public behaviour or API; needs a minor/major release labels Sep 30, 2026
@allen0099
allen0099 merged commit 2a65b89 into master Sep 30, 2026
17 checks passed
@allen0099
allen0099 deleted the feat/256-host-cookie-default branch September 30, 2026 10:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

breaking-change Changes public behaviour or API; needs a minor/major release enhancement New feature or request session Session management subsystem

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant