docs(sensitive-data): Overhaul docs around HTTP headers (#15616)

## DESCRIBE YOUR PR

Being more explicit about which HTTP headers we consider as sensitive
and how SDKs should handle the data.

## IS YOUR CHANGE URGENT?  

Help us prioritize incoming PRs by letting us know when the change needs
to go live.
- [ ] Urgent deadline (GA date, etc.): <!-- ENTER DATE HERE -->
- [ ] Other deadline: <!-- ENTER DATE HERE -->
- [ ] None: Not urgent, can wait up to 1 week+

## SLA

- Teamwork makes the dream work, so please add a reviewer to your PRs.
- Please give the docs team up to 1 week to review your PR unless you've
added an urgent due date to it.
Thanks in advance for your help!

## PRE-MERGE CHECKLIST

*Make sure you've checked the following before merging your changes:*

- [ ] Checked Vercel preview for correctness, including links
- [ ] PR was reviewed and approved by any necessary SMEs (subject matter
experts)
- [ ] PR was reviewed and approved by a member of the [Sentry docs
team](https://github.com/orgs/getsentry/teams/docs)

---------

Co-authored-by: Michi Hoffmann <cleptric@users.noreply.github.com>

Author: s1gr1d

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

@@ -13,13 +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.
 
-Some examples of data guarded by this flag:
+Certain sensitive data must never be sent through SDK instrumentation, regardless of any configuration:
+
+- 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", "pwd", "key", "jwt", "bearer", "sso", "saml", "csrf", "xsrf", "credentials"]`
+
+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
-  - HTTP Headers: known sensitive headers such as `Authorization` or `Cookie` are removed too.
+  - 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`
@@ -33,6 +41,21 @@ 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 `Cookie` and `Set-Cookie` headers 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 cookie for the theme preference 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.set_cookie.theme: "light-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.

develop-docs/sdk/expected-features/index.mdx

@@ -373,7 +373,7 @@ The HTTP Client integration should have 3 configuration options:
   - If the language has a `Range` type, it should be used instead of `HttpStatusCodeRange`.
 - `failedRequestTargets` defaults to (`.*`), this configuration option accepts a `List` of `String` that may be Regular expressions as well, similar to <Link to="/sdk/telemetry/traces/#tracepropagationtargets">tracePropagationTargets</Link>.
   - The SDK will only capture HTTP Client errors if the HTTP Request URL is a match for any of the `failedRequestsTargets`.
--  sensitive `headers` should only be set if `sendDefaultPii` is enabled, e.g. `Cookie` and `Set-Cookie`.
+-  While the keys of sensitive HTTP headers (e.g. `Authorization` and `Cookie`) are included, their values must be replaced with `"[Filtered]"` (also see <Link to="/sdk/expected-features/data-handling/#sensitive-data">Data Handling: Sensitive Data</Link>).
 
 The HTTP Client integration should capture error events with the following properties: