Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""
2Internal cookie handling helpers.
4This module contains internal utilities for cookie parsing and manipulation.
5These are not part of the public API and may change without notice.
6"""
8import re
9from http.cookies import Morsel
10from typing import List, Optional, Sequence, Tuple, cast
12from .log import internal_logger
14__all__ = (
15 "parse_set_cookie_headers",
16 "parse_cookie_header",
17 "preserve_morsel_with_coded_value",
18)
20# Cookie parsing constants
21# Allow more characters in cookie names to handle real-world cookies
22# that don't strictly follow RFC standards (fixes #2683)
23# RFC 6265 defines cookie-name token as per RFC 2616 Section 2.2,
24# but many servers send cookies with characters like {} [] () etc.
25# This makes the cookie parser more tolerant of real-world cookies
26# while still providing some validation to catch obviously malformed names.
27_COOKIE_NAME_RE = re.compile(r"^[!#$%&\'()*+\-./0-9:<=>?@A-Z\[\]^_`a-z{|}~]+$")
28_COOKIE_KNOWN_ATTRS = frozenset( # AKA Morsel._reserved
29 (
30 "path",
31 "domain",
32 "max-age",
33 "expires",
34 "secure",
35 "httponly",
36 "samesite",
37 "partitioned",
38 "version",
39 "comment",
40 )
41)
42_COOKIE_BOOL_ATTRS = frozenset( # AKA Morsel._flags
43 ("secure", "httponly", "partitioned")
44)
46# SimpleCookie's pattern for parsing cookies with relaxed validation
47# Based on http.cookies pattern but extended to allow more characters in cookie names
48# to handle real-world cookies (fixes #2683)
49_COOKIE_PATTERN = re.compile(
50 r"""
51 \s* # Optional whitespace at start of cookie
52 (?P<key> # Start of group 'key'
53 # aiohttp has extended to include [] for compatibility with real-world cookies
54 [\w\d!#%&'~_`><@,:/\$\*\+\-\.\^\|\)\(\?\}\{\=\[\]]+? # Any word of at least one letter
55 ) # End of group 'key'
56 ( # Optional group: there may not be a value.
57 \s*=\s* # Equal Sign
58 (?P<val> # Start of group 'val'
59 "(?:[^\\"]|\\.)*" # Any double-quoted string (properly closed)
60 | # or
61 "[^";]* # Unmatched opening quote (differs from SimpleCookie - issue #7993)
62 | # or
63 # Special case for "expires" attr - RFC 822, RFC 850, RFC 1036, RFC 1123
64 (\w{3,6}day|\w{3}),\s # Day of the week or abbreviated day (with comma)
65 [\w\d\s-]{9,11}\s[\d:]{8}\s # Date and time in specific format
66 (GMT|[+-]\d{4}) # Timezone: GMT or RFC 2822 offset like -0000, +0100
67 # NOTE: RFC 2822 timezone support is an aiohttp extension
68 # for issue #4493 - SimpleCookie does NOT support this
69 | # or
70 # ANSI C asctime() format: "Wed Jun 9 10:18:14 2021"
71 # NOTE: This is an aiohttp extension for issue #4327 - SimpleCookie does NOT support this format
72 \w{3}\s+\w{3}\s+[\s\d]\d\s+\d{2}:\d{2}:\d{2}\s+\d{4}
73 | # or
74 [\w\d!#%&'~_`><@,:/\$\*\+\-\.\^\|\)\(\?\}\{\=\[\]]* # Any word or empty string
75 ) # End of group 'val'
76 )? # End of optional value group
77 \s* # Any number of spaces.
78 (\s+|;|$) # Ending either at space, semicolon, or EOS.
79 """,
80 re.VERBOSE | re.ASCII,
81)
84def preserve_morsel_with_coded_value(cookie: Morsel[str]) -> Morsel[str]:
85 """
86 Preserve a Morsel's coded_value exactly as received from the server.
88 This function ensures that cookie encoding is preserved exactly as sent by
89 the server, which is critical for compatibility with old servers that have
90 strict requirements about cookie formats.
92 This addresses the issue described in https://github.com/aio-libs/aiohttp/pull/1453
93 where Python's SimpleCookie would re-encode cookies, breaking authentication
94 with certain servers.
96 Args:
97 cookie: A Morsel object from SimpleCookie
99 Returns:
100 A Morsel object with preserved coded_value
102 """
103 mrsl_val = cast("Morsel[str]", cookie.get(cookie.key, Morsel()))
104 # We use __setstate__ instead of the public set() API because it allows us to
105 # bypass validation and set already validated state. This is more stable than
106 # setting protected attributes directly and unlikely to change since it would
107 # break pickling.
108 mrsl_val.__setstate__( # type: ignore[attr-defined]
109 {"key": cookie.key, "value": cookie.value, "coded_value": cookie.coded_value}
110 )
111 return mrsl_val
114_unquote_sub = re.compile(r"\\(?:([0-3][0-7][0-7])|(.))").sub
117def _unquote_replace(m: re.Match[str]) -> str:
118 """
119 Replace function for _unquote_sub regex substitution.
121 Handles escaped characters in cookie values:
122 - Octal sequences are converted to their character representation
123 - Other escaped characters are unescaped by removing the backslash
124 """
125 if m[1]:
126 return chr(int(m[1], 8))
127 return m[2]
130def _unquote(value: str) -> str:
131 """
132 Unquote a cookie value.
134 Vendored from http.cookies._unquote to ensure compatibility.
136 Note: The original implementation checked for None, but we've removed
137 that check since all callers already ensure the value is not None.
138 """
139 # If there aren't any doublequotes,
140 # then there can't be any special characters. See RFC 2109.
141 if len(value) < 2:
142 return value
143 if value[0] != '"' or value[-1] != '"':
144 return value
146 # We have to assume that we must decode this string.
147 # Down to work.
149 # Remove the "s
150 value = value[1:-1]
152 # Check for special sequences. Examples:
153 # \012 --> \n
154 # \" --> "
155 #
156 return _unquote_sub(_unquote_replace, value)
159def parse_cookie_header(header: str) -> List[Tuple[str, Morsel[str]]]:
160 """
161 Parse a Cookie header according to RFC 6265 Section 5.4.
163 Cookie headers contain only name-value pairs separated by semicolons.
164 There are no attributes in Cookie headers - even names that match
165 attribute names (like 'path' or 'secure') should be treated as cookies.
167 This parser uses the same regex-based approach as parse_set_cookie_headers
168 to properly handle quoted values that may contain semicolons.
170 Args:
171 header: The Cookie header value to parse
173 Returns:
174 List of (name, Morsel) tuples for compatibility with SimpleCookie.update()
175 """
176 if not header:
177 return []
179 cookies: List[Tuple[str, Morsel[str]]] = []
180 i = 0
181 n = len(header)
183 while i < n:
184 # Use the same pattern as parse_set_cookie_headers to find cookies
185 match = _COOKIE_PATTERN.match(header, i)
186 if not match:
187 break
189 key = match.group("key")
190 value = match.group("val") or ""
191 i = match.end(0)
193 # Validate the name
194 if not key or not _COOKIE_NAME_RE.match(key):
195 internal_logger.warning("Can not load cookie: Illegal cookie name %r", key)
196 continue
198 # Create new morsel
199 morsel: Morsel[str] = Morsel()
200 # Preserve the original value as coded_value (with quotes if present)
201 # We use __setstate__ instead of the public set() API because it allows us to
202 # bypass validation and set already validated state. This is more stable than
203 # setting protected attributes directly and unlikely to change since it would
204 # break pickling.
205 morsel.__setstate__( # type: ignore[attr-defined]
206 {"key": key, "value": _unquote(value), "coded_value": value}
207 )
209 cookies.append((key, morsel))
211 return cookies
214def parse_set_cookie_headers(headers: Sequence[str]) -> List[Tuple[str, Morsel[str]]]:
215 """
216 Parse cookie headers using a vendored version of SimpleCookie parsing.
218 This implementation is based on SimpleCookie.__parse_string to ensure
219 compatibility with how SimpleCookie parses cookies, including handling
220 of malformed cookies with missing semicolons.
222 This function is used for both Cookie and Set-Cookie headers in order to be
223 forgiving. Ideally we would have followed RFC 6265 Section 5.2 (for Cookie
224 headers) and RFC 6265 Section 4.2.1 (for Set-Cookie headers), but the
225 real world data makes it impossible since we need to be a bit more forgiving.
227 NOTE: This implementation differs from SimpleCookie in handling unmatched quotes.
228 SimpleCookie will stop parsing when it encounters a cookie value with an unmatched
229 quote (e.g., 'cookie="value'), causing subsequent cookies to be silently dropped.
230 This implementation handles unmatched quotes more gracefully to prevent cookie loss.
231 See https://github.com/aio-libs/aiohttp/issues/7993
232 """
233 parsed_cookies: List[Tuple[str, Morsel[str]]] = []
235 for header in headers:
236 if not header:
237 continue
239 # Parse cookie string using SimpleCookie's algorithm
240 i = 0
241 n = len(header)
242 current_morsel: Optional[Morsel[str]] = None
243 morsel_seen = False
245 while 0 <= i < n:
246 # Start looking for a cookie
247 match = _COOKIE_PATTERN.match(header, i)
248 if not match:
249 # No more cookies
250 break
252 key, value = match.group("key"), match.group("val")
253 i = match.end(0)
254 lower_key = key.lower()
256 if key[0] == "$":
257 if not morsel_seen:
258 # We ignore attributes which pertain to the cookie
259 # mechanism as a whole, such as "$Version".
260 continue
261 # Process as attribute
262 if current_morsel is not None:
263 attr_lower_key = lower_key[1:]
264 if attr_lower_key in _COOKIE_KNOWN_ATTRS:
265 current_morsel[attr_lower_key] = value or ""
266 elif lower_key in _COOKIE_KNOWN_ATTRS:
267 if not morsel_seen:
268 # Invalid cookie string - attribute before cookie
269 break
270 if lower_key in _COOKIE_BOOL_ATTRS:
271 # Boolean attribute with any value should be True
272 if current_morsel is not None and current_morsel.isReservedKey(key):
273 current_morsel[lower_key] = True
274 elif value is None:
275 # Invalid cookie string - non-boolean attribute without value
276 break
277 elif current_morsel is not None:
278 # Regular attribute with value
279 current_morsel[lower_key] = _unquote(value)
280 elif value is not None:
281 # This is a cookie name=value pair
282 # Validate the name
283 if key in _COOKIE_KNOWN_ATTRS or not _COOKIE_NAME_RE.match(key):
284 internal_logger.warning(
285 "Can not load cookies: Illegal cookie name %r", key
286 )
287 current_morsel = None
288 else:
289 # Create new morsel
290 current_morsel = Morsel()
291 # Preserve the original value as coded_value (with quotes if present)
292 # We use __setstate__ instead of the public set() API because it allows us to
293 # bypass validation and set already validated state. This is more stable than
294 # setting protected attributes directly and unlikely to change since it would
295 # break pickling.
296 current_morsel.__setstate__( # type: ignore[attr-defined]
297 {"key": key, "value": _unquote(value), "coded_value": value}
298 )
299 parsed_cookies.append((key, current_morsel))
300 morsel_seen = True
301 else:
302 # Invalid cookie string - no value for non-attribute
303 break
305 return parsed_cookies