review suggestions, cookie addition

Author: s1gr1d

develop-docs/sdk/expected-features/data-handling.mdx

@@ -13,24 +13,21 @@ In the event that API returns data considered PII, we guard that behind a flag c
 This is an option in the SDK called [_send-default-pii_](https://docs.sentry.io/platforms/python/configuration/options/#send-default-pii)
 and is **disabled by default**. That means that data that is naturally sensitive is not sent by default.
 
-Handling sensitive data in the SDK regardless of the `send_default_pii` setting:
+Certain sensitive data must never been sent by the SDK, regardless of any config:
 
-- HTTP Headers: The keys of known sensitive headers (such as `Authorization` or `Cookie`) are added, while their values must be replaced with `"[Filtered]"`.
+- HTTP Headers: The keys of known sensitive headers are added, while their values must be replaced with `"[Filtered]"`.
+  - The SDK performs a **partial, case-insensitive match** against the following headers to determine if they are sensitive: `["auth", "token", "secret", "password", "passwd", "key", "jwt", "bearer", "sso", "saml", "crsf", "xsrf", "credentials"]`
 
-<Expandable title="List of sensitive HTTP headers">
-
-  The SDK performs a **partial, case-insensitive match** against the following headers to determine if they are sensitive:
-
-  `['auth', 'token', 'secret', 'cookie', '-user', 'password', 'key', 'jwt', 'bearer', 'sso', 'saml']`
-
-</Expandable>
+SDKs should only replace sensitive data with `"[Filtered]"` when the data is gathered automatically through instrumentation.
+If a user explicitly provides data (for example, by setting a request object on the scope), the SDK must not modify it.
 
 Some examples of data guarded by `send_default_pii: false`:
 
 - When attaching data of HTTP requests and/or responses to events
-  - Request Body: "raw" HTTP bodies (bodies which cannot be parsed as JSON or formdata) are removed
+  - Request Body: "raw" HTTP bodies (bodies which cannot be parsed as JSON or FormData) are removed
+  - HTTP Headers: header values, containing information about the user are replaced with `"[Filtered]"`
   - _Note_ that if a user explicitly sets a request on the scope, nothing is stripped from that request. The above rules only apply to integrations that come with the SDK.
-- User-specific information (e.g. the current user ID according to the used web-framework) is not sent at all.
+- User-specific information (e.g. the current user ID according to the used web-framework) is not collected and therefore not sent at all.
 - On desktop applications
   - The username logged in the device is not included. This is often a person's name.
   - The machine name is not included, for example `Bruno's laptop`
@@ -44,6 +41,20 @@ Before sending events to Sentry, the SDKs should invokes callbacks. That allows
 
 - [`before-send` and `event-processors`](/sdk/miscellaneous/unified-api/#static-api) can be used to register a callback with custom logic to remove sensitive data.
 
+### Cookies
+
+Since cookies can contain a mix of sensitive and non-sensitive data, SDKs should parse the cookie header and filter values on a per-key basis, depending on the SDK setting and the sensitivity of the cookie value.
+In case, the SDK cannot parse each cookie key-value pair, the entire cookie header must be replaced with `"[Filtered]"`. An unfiltered, raw cookie header value must never be sent.
+
+This selective filtering prevents capturing sensitive data while retaining harmless contextual information for debugging.
+For example, a sensitive session cookie's value is replaced with "[Filtered]", but a non-sensitive theme cookie can be sent as-is.
+
+When attached as span attributes, the results should be as follows:
+
+- `http.request.header.cookie.user_session: "[Filtered]"`
+- `http.request.header.cookie.theme: "dark-mode"`
+- `http.request.header.cookie: "[Filtered]"` (Used as a fallback if the cookie header cannot be parsed)
+
 ### Application State
 
 App state can be critical to help developers reproduce bugs. For that reason, SDKs often collect app state and append to events through auto instrumentation.