venv/lib/python3.11/site-packages/flask/sessions.py

   1 from __future__ import annotations
   2
   3 import hashlib
   4 import typing as t
   5 from collections.abc import MutableMapping
   6 from datetime import datetime
   7 from datetime import timezone
   8
   9 from itsdangerous import BadSignature
  10 from itsdangerous import URLSafeTimedSerializer
  11 from werkzeug.datastructures import CallbackDict
  12
  13 from .json.tag import TaggedJSONSerializer
  14
  15 if t.TYPE_CHECKING:  # pragma: no cover
  16     from .app import Flask
  17     from .wrappers import Request, Response
  18
  19
  20 class SessionMixin(MutableMapping):
  21     """Expands a basic dictionary with session attributes."""
  22
  23     @property
  24     def permanent(self) -> bool:
  25         """This reflects the ``'_permanent'`` key in the dict."""
  26         return self.get("_permanent", False)
  27
  28     @permanent.setter
  29     def permanent(self, value: bool) -> None:
  30         self["_permanent"] = bool(value)
  31
  32     #: Some implementations can detect whether a session is newly
  33     #: created, but that is not guaranteed. Use with caution. The mixin
  34     # default is hard-coded ``False``.
  35     new = False
  36
  37     #: Some implementations can detect changes to the session and set
  38     #: this when that happens. The mixin default is hard coded to
  39     #: ``True``.
  40     modified = True
  41
  42     #: Some implementations can detect when session data is read or
  43     #: written and set this when that happens. The mixin default is hard
  44     #: coded to ``True``.
  45     accessed = True
  46
  47
  48 class SecureCookieSession(CallbackDict, SessionMixin):
  49     """Base class for sessions based on signed cookies.
  50
  51     This session backend will set the :attr:`modified` and
  52     :attr:`accessed` attributes. It cannot reliably track whether a
  53     session is new (vs. empty), so :attr:`new` remains hard coded to
  54     ``False``.
  55     """
  56
  57     #: When data is changed, this is set to ``True``. Only the session
  58     #: dictionary itself is tracked; if the session contains mutable
  59     #: data (for example a nested dict) then this must be set to
  60     #: ``True`` manually when modifying that data. The session cookie
  61     #: will only be written to the response if this is ``True``.
  62     modified = False
  63
  64     #: When data is read or written, this is set to ``True``. Used by
  65     # :class:`.SecureCookieSessionInterface` to add a ``Vary: Cookie``
  66     #: header, which allows caching proxies to cache different pages for
  67     #: different users.
  68     accessed = False
  69
  70     def __init__(self, initial: t.Any = None) -> None:
  71         def on_update(self) -> None:
  72             self.modified = True
  73             self.accessed = True
  74
  75         super().__init__(initial, on_update)
  76
  77     def __getitem__(self, key: str) -> t.Any:
  78         self.accessed = True
  79         return super().__getitem__(key)
  80
  81     def get(self, key: str, default: t.Any = None) -> t.Any:
  82         self.accessed = True
  83         return super().get(key, default)
  84
  85     def setdefault(self, key: str, default: t.Any = None) -> t.Any:
  86         self.accessed = True
  87         return super().setdefault(key, default)
  88
  89
  90 class NullSession(SecureCookieSession):
  91     """Class used to generate nicer error messages if sessions are not
  92     available.  Will still allow read-only access to the empty session
  93     but fail on setting.
  94     """
  95
  96     def _fail(self, *args: t.Any, **kwargs: t.Any) -> t.NoReturn:
  97         raise RuntimeError(
  98             "The session is unavailable because no secret "
  99             "key was set.  Set the secret_key on the "
 100             "application to something unique and secret."
 101         )
 102
 103     __setitem__ = __delitem__ = clear = pop = popitem = update = setdefault = _fail  # type: ignore # noqa: B950
 104     del _fail
 105
 106
 107 class SessionInterface:
 108     """The basic interface you have to implement in order to replace the
 109     default session interface which uses werkzeug's securecookie
 110     implementation.  The only methods you have to implement are
 111     :meth:`open_session` and :meth:`save_session`, the others have
 112     useful defaults which you don't need to change.
 113
 114     The session object returned by the :meth:`open_session` method has to
 115     provide a dictionary like interface plus the properties and methods
 116     from the :class:`SessionMixin`.  We recommend just subclassing a dict
 117     and adding that mixin::
 118
 119         class Session(dict, SessionMixin):
 120             pass
 121
 122     If :meth:`open_session` returns ``None`` Flask will call into
 123     :meth:`make_null_session` to create a session that acts as replacement
 124     if the session support cannot work because some requirement is not
 125     fulfilled.  The default :class:`NullSession` class that is created
 126     will complain that the secret key was not set.
 127
 128     To replace the session interface on an application all you have to do
 129     is to assign :attr:`flask.Flask.session_interface`::
 130
 131         app = Flask(__name__)
 132         app.session_interface = MySessionInterface()
 133
 134     Multiple requests with the same session may be sent and handled
 135     concurrently. When implementing a new session interface, consider
 136     whether reads or writes to the backing store must be synchronized.
 137     There is no guarantee on the order in which the session for each
 138     request is opened or saved, it will occur in the order that requests
 139     begin and end processing.
 140
 141     .. versionadded:: 0.8
 142     """
 143
 144     #: :meth:`make_null_session` will look here for the class that should
 145     #: be created when a null session is requested.  Likewise the
 146     #: :meth:`is_null_session` method will perform a typecheck against
 147     #: this type.
 148     null_session_class = NullSession
 149
 150     #: A flag that indicates if the session interface is pickle based.
 151     #: This can be used by Flask extensions to make a decision in regards
 152     #: to how to deal with the session object.
 153     #:
 154     #: .. versionadded:: 0.10
 155     pickle_based = False
 156
 157     def make_null_session(self, app: Flask) -> NullSession:
 158         """Creates a null session which acts as a replacement object if the
 159         real session support could not be loaded due to a configuration
 160         error.  This mainly aids the user experience because the job of the
 161         null session is to still support lookup without complaining but
 162         modifications are answered with a helpful error message of what
 163         failed.
 164
 165         This creates an instance of :attr:`null_session_class` by default.
 166         """
 167         return self.null_session_class()
 168
 169     def is_null_session(self, obj: object) -> bool:
 170         """Checks if a given object is a null session.  Null sessions are
 171         not asked to be saved.
 172
 173         This checks if the object is an instance of :attr:`null_session_class`
 174         by default.
 175         """
 176         return isinstance(obj, self.null_session_class)
 177
 178     def get_cookie_name(self, app: Flask) -> str:
 179         """The name of the session cookie. Uses``app.config["SESSION_COOKIE_NAME"]``."""
 180         return app.config["SESSION_COOKIE_NAME"]
 181
 182     def get_cookie_domain(self, app: Flask) -> str | None:
 183         """The value of the ``Domain`` parameter on the session cookie. If not set,
 184         browsers will only send the cookie to the exact domain it was set from.
 185         Otherwise, they will send it to any subdomain of the given value as well.
 186
 187         Uses the :data:`SESSION_COOKIE_DOMAIN` config.
 188
 189         .. versionchanged:: 2.3
 190             Not set by default, does not fall back to ``SERVER_NAME``.
 191         """
 192         rv = app.config["SESSION_COOKIE_DOMAIN"]
 193         return rv if rv else None
 194
 195     def get_cookie_path(self, app: Flask) -> str:
 196         """Returns the path for which the cookie should be valid.  The
 197         default implementation uses the value from the ``SESSION_COOKIE_PATH``
 198         config var if it's set, and falls back to ``APPLICATION_ROOT`` or
 199         uses ``/`` if it's ``None``.
 200         """
 201         return app.config["SESSION_COOKIE_PATH"] or app.config["APPLICATION_ROOT"]
 202
 203     def get_cookie_httponly(self, app: Flask) -> bool:
 204         """Returns True if the session cookie should be httponly.  This
 205         currently just returns the value of the ``SESSION_COOKIE_HTTPONLY``
 206         config var.
 207         """
 208         return app.config["SESSION_COOKIE_HTTPONLY"]
 209
 210     def get_cookie_secure(self, app: Flask) -> bool:
 211         """Returns True if the cookie should be secure.  This currently
 212         just returns the value of the ``SESSION_COOKIE_SECURE`` setting.
 213         """
 214         return app.config["SESSION_COOKIE_SECURE"]
 215
 216     def get_cookie_samesite(self, app: Flask) -> str:
 217         """Return ``'Strict'`` or ``'Lax'`` if the cookie should use the
 218         ``SameSite`` attribute. This currently just returns the value of
 219         the :data:`SESSION_COOKIE_SAMESITE` setting.
 220         """
 221         return app.config["SESSION_COOKIE_SAMESITE"]
 222
 223     def get_expiration_time(self, app: Flask, session: SessionMixin) -> datetime | None:
 224         """A helper method that returns an expiration date for the session
 225         or ``None`` if the session is linked to the browser session.  The
 226         default implementation returns now + the permanent session
 227         lifetime configured on the application.
 228         """
 229         if session.permanent:
 230             return datetime.now(timezone.utc) + app.permanent_session_lifetime
 231         return None
 232
 233     def should_set_cookie(self, app: Flask, session: SessionMixin) -> bool:
 234         """Used by session backends to determine if a ``Set-Cookie`` header
 235         should be set for this session cookie for this response. If the session
 236         has been modified, the cookie is set. If the session is permanent and
 237         the ``SESSION_REFRESH_EACH_REQUEST`` config is true, the cookie is
 238         always set.
 239
 240         This check is usually skipped if the session was deleted.
 241
 242         .. versionadded:: 0.11
 243         """
 244
 245         return session.modified or (
 246             session.permanent and app.config["SESSION_REFRESH_EACH_REQUEST"]
 247         )
 248
 249     def open_session(self, app: Flask, request: Request) -> SessionMixin | None:
 250         """This is called at the beginning of each request, after
 251         pushing the request context, before matching the URL.
 252
 253         This must return an object which implements a dictionary-like
 254         interface as well as the :class:`SessionMixin` interface.
 255
 256         This will return ``None`` to indicate that loading failed in
 257         some way that is not immediately an error. The request
 258         context will fall back to using :meth:`make_null_session`
 259         in this case.
 260         """
 261         raise NotImplementedError()
 262
 263     def save_session(
 264         self, app: Flask, session: SessionMixin, response: Response
 265     ) -> None:
 266         """This is called at the end of each request, after generating
 267         a response, before removing the request context. It is skipped
 268         if :meth:`is_null_session` returns ``True``.
 269         """
 270         raise NotImplementedError()
 271
 272
 273 session_json_serializer = TaggedJSONSerializer()
 274
 275
 276 class SecureCookieSessionInterface(SessionInterface):
 277     """The default session interface that stores sessions in signed cookies
 278     through the :mod:`itsdangerous` module.
 279     """
 280
 281     #: the salt that should be applied on top of the secret key for the
 282     #: signing of cookie based sessions.
 283     salt = "cookie-session"
 284     #: the hash function to use for the signature.  The default is sha1
 285     digest_method = staticmethod(hashlib.sha1)
 286     #: the name of the itsdangerous supported key derivation.  The default
 287     #: is hmac.
 288     key_derivation = "hmac"
 289     #: A python serializer for the payload.  The default is a compact
 290     #: JSON derived serializer with support for some extra Python types
 291     #: such as datetime objects or tuples.
 292     serializer = session_json_serializer
 293     session_class = SecureCookieSession
 294
 295     def get_signing_serializer(self, app: Flask) -> URLSafeTimedSerializer | None:
 296         if not app.secret_key:
 297             return None
 298         signer_kwargs = dict(
 299             key_derivation=self.key_derivation, digest_method=self.digest_method
 300         )
 301         return URLSafeTimedSerializer(
 302             app.secret_key,
 303             salt=self.salt,
 304             serializer=self.serializer,
 305             signer_kwargs=signer_kwargs,
 306         )
 307
 308     def open_session(self, app: Flask, request: Request) -> SecureCookieSession | None:
 309         s = self.get_signing_serializer(app)
 310         if s is None:
 311             return None
 312         val = request.cookies.get(self.get_cookie_name(app))
 313         if not val:
 314             return self.session_class()
 315         max_age = int(app.permanent_session_lifetime.total_seconds())
 316         try:
 317             data = s.loads(val, max_age=max_age)
 318             return self.session_class(data)
 319         except BadSignature:
 320             return self.session_class()
 321
 322     def save_session(
 323         self, app: Flask, session: SessionMixin, response: Response
 324     ) -> None:
 325         name = self.get_cookie_name(app)
 326         domain = self.get_cookie_domain(app)
 327         path = self.get_cookie_path(app)
 328         secure = self.get_cookie_secure(app)
 329         samesite = self.get_cookie_samesite(app)
 330         httponly = self.get_cookie_httponly(app)
 331
 332         # Add a "Vary: Cookie" header if the session was accessed at all.
 333         if session.accessed:
 334             response.vary.add("Cookie")
 335
 336         # If the session is modified to be empty, remove the cookie.
 337         # If the session is empty, return without setting the cookie.
 338         if not session:
 339             if session.modified:
 340                 response.delete_cookie(
 341                     name,
 342                     domain=domain,
 343                     path=path,
 344                     secure=secure,
 345                     samesite=samesite,
 346                     httponly=httponly,
 347                 )
 348                 response.vary.add("Cookie")
 349
 350             return
 351
 352         if not self.should_set_cookie(app, session):
 353             return
 354
 355         expires = self.get_expiration_time(app, session)
 356         val = self.get_signing_serializer(app).dumps(dict(session))  # type: ignore
 357         response.set_cookie(
 358             name,
 359             val,  # type: ignore
 360             expires=expires,
 361             httponly=httponly,
 362             domain=domain,
 363             path=path,
 364             secure=secure,
 365             samesite=samesite,
 366         )
 367         response.vary.add("Cookie")