cookie-debugging

核心概念

页面定位：页面级工具（list_network_requests、get_network_request、list_console_messages、evaluate_script、navigate_page、take_snapshot、click、lighthouse_audit、close_page 等）需要 pageId 参数。使用 list_pages 或从 new_page 获取可用的页面 ID。

HttpOnly 与客户端存储

标记为 HttpOnly 的 Cookie 无法被客户端 JavaScript（cookieStore 或 document.cookie）访问或修改。但是，浏览器会自动将有效的 HttpOnly Cookie 附加到传出的 HTTP 请求头（Cookie）中。

• 检查当前 HttpOnly 值：通过 get_network_request 查看任意传出 HTTP 请求的 Cookie 请求头。
• 检查 Cookie 是如何创建或配置的：查看登录/认证响应的 Set-Cookie 响应头。
• 检查非 HttpOnly Cookie：使用 evaluate_script 配合现代的 cookieStore API（async () => await cookieStore.getAll()）。

会话策略：活动标签页与隔离上下文

选择合适的会话环境，避免状态污染（例如残留的分析数据或认证令牌）：

策略	使用场景	设置 / 清理
活动标签页（活动页面）	诊断活动用户会话、实时 401/403 错误或当前状态。	在用户现有页面上操作；从 list_pages 获取其 pageId。
干净状态（isolatedContext）	测试 Cookie 同意横幅、首次访问或零 Cookie 保证。	使用唯一的 isolatedContext（例如 "consent-audit-1"）调用 new_page。完成后调用 close_page。

客户端能力与限制

操作	客户端 JavaScript（cookieStore / document.cookie）	DevTools 网络与上下文工具
读取非 HttpOnly	✅ async () => await cookieStore.getAll()	✅ get_network_request（请求 Cookie）
读取 HttpOnly	❌ 被浏览器安全策略阻止	✅ get_network_request（请求 Cookie）
检查属性（Domain、Path、SameSite、Expires）	✅ async () => await cookieStore.getAll()	✅ get_network_request（响应 Set-Cookie）
修改 / 删除非 HttpOnly	✅ async () => await cookieStore.set(...)	不适用
修改 / 删除 HttpOnly	❌ 在 JavaScript 中静默失败	✅ 使用 new_page(isolatedContext: ...) 获得干净状态

警告

尝试通过 JavaScript（cookieStore.delete 或 document.cookie = "...; max-age=0"）清除 HttpOnly Cookie 会静默失败。要在未认证或全新状态下测试，请始终使用 new_page 配合 isolatedContext 生成新的隔离上下文。

---

工作流模式

1. 诊断认证失败与重定向（401 / 403）

当已认证的页面请求失败、返回 401/403，或重定向到登录页时：

1. 列出最近的请求：调用 list_network_requests，并设置 includePreservedRequests: true。
2. 找到目标请求：定位失败的请求（401/403）或重定向（302/307）。
3. 检查发出的 Cookie 请求头：使用 reqid 调用 get_network_request。
   • 验证是否附带了 Cookie 请求头，以及是否发送了所需的令牌（例如 SESSION_ID、auth_token）。
4. 触发主动检查（如果不存在最近的请求）：
   • 如果 cookie 是在之前的会话中设置的，且没有列出网络调用，请触发一个请求：
     • 使用 navigate_page，并设置 type: "reload"，或
     • 调用 evaluate_script，并传入 () => fetch(window.location.href)
   • 然后对新请求调用 get_network_request，以检查当前生效的 Cookie 请求头。
5. 追踪设置 cookie 的请求：如果 cookie 缺失或被拒绝：
   • 检查更早的登录/握手响应中的 Set-Cookie 指令：
     • Path 不匹配：例如请求的是 /，而 cookie 为 Path=/api。
     • Domain 不匹配：例如 Domain=api.example.com 导致 cookie 无法用于 sub.example.com。
     • HTTP 上的 Secure 标志：Secure cookie 绝不会通过未加密的 http:// 发送。
     • SameSite 阻止：跨站导航时会省略 SameSite=Strict cookie。
     • 过期：检查 Expires 或 Max-Age 是否已过。

2. Cookie 横幅与同意合规性测试

要验证在同意之前或拒绝时未设置任何非必要或跟踪 cookie：

1. 从干净状态开始：使用专用名称打开一个全新的隔离上下文：

   {"url": "<PAGE_URL>", "isolatedContext": "consent-test-1"}
   

2. 记录基线 Cookie：在与横幅交互之前，运行 evaluate_script，并传入 async () => await cookieStore.getAll()。
3. 检查过早的网络请求与问题：
   • 调用 list_network_requests，确保在同意之前没有触发任何第三方跟踪信标。
   • 调用 list_console_messages，并设置 types: ["issue"]，以检查跟踪警告。
4. 与同意横幅交互：
   • 使用 take_snapshot 捕获快照，以定位“拒绝”或“全部拒绝”按钮的 uid。
   • 使用 click 点击该按钮。
5. 验证 Cookie 差异：
   • 点击后运行 evaluate_script，并传入 async () => await cookieStore.getAll()，以断言仅存在严格必要的 cookie 或同意状态 cookie。
6. 测试同意撤回（生命周期审计）：
   • 在审计同意撤回或偏好更改时：
     • 定位并点击“Cookie 设置”、“管理偏好”或页脚隐私触发器（take_snapshot $\rightarrow$ click）。
     • 取消选择非必要类别，或点击“全部撤回”/“保存偏好”。
     • 重新查询 cookieStore.getAll()，以验证之前已接受的非必要 cookie 已被清除或过期。
     • 对后续操作调用 list_network_requests，以确保跟踪信标不再触发。
7. 拆除上下文：审计完成后调用 close_page，以防止残留 cookie 影响后续任务。

3. 审计 Cookie 安全性、SameSite 和 CHIPS（分区 Cookie）

1. 快速检查：原生 DevTools 问题（推荐）：
   • 调用 list_console_messages，并传入：

     {
       "pageId": 1,
       "types": ["issue"],
       "includePreservedMessages": true
     }
     

   • 检查 CookieIssue 条目，例如：
     • SameSiteNoneInsecure：SameSite=None 未设置 Secure。
     • ThirdPartyCookiePhaseout：第三方 Cookie 被拦截或受到限制。
     • SchemefulSameSite：跨 Scheme 的 Cookie 问题。
     • PartitionedCookies：CHIPS 分区属性无效。
2. 深度审计：Lighthouse 第三方 Cookie：
   • 运行 lighthouse_audit，并设置 mode: "navigation"（省略 outputDirPath 以使用默认临时文件，或指定工作区内的目录）。
   • 从返回的 report.json 路径中提取具体的 Cookie 审计结果，而不将完整报告加载到上下文中：

     node -e "const r=require('<path/to/report.json>'); const a=r.audits['third-party-cookies']; console.log(JSON.stringify({score: a?.score, displayValue: a?.displayValue, items: a?.details?.items}))"
     

4. 客户端 Cookie 检查与操作

对于客户端可访问的非 HttpOnly Cookie（例如 UI 偏好设置、非敏感功能标志）：

1. 读取 Cookie 和属性：
   • 使用现代异步 Cookie Store API：

     async () => await cookieStore.getAll();
     

   • 不安全 HTTP 来源的回退方式：() => document.cookie。
2. 设置 / 修改 Cookie：
   • 通过 cookieStore 设置客户端 Cookie：

     async () =>
       await cookieStore.set({
         name: 'theme',
         value: 'dark',
         expires: Date.now() + 86400000,
         sameSite: 'lax',
       });
     

3. 删除 Cookie：
   • 清除客户端 Cookie：

     async () => await cookieStore.delete('theme');
     

---

故障排除

• cookieStore 未定义：cookieStore 需要安全上下文（https://、localhost 或 127.0.0.1）。对于非安全 HTTP 来源，请使用 () => document.cookie，或通过 HTTPS 进行测试。
• evaluate_script 返回空结果 / 未解析的 Promise：cookieStore 方法是异步的。始终使用 async () => await cookieStore.getAll() 包装调用。
• JavaScript 中看不到 Cookie：该 Cookie 标记为 HttpOnly。触发网络请求，并调用 get_network_request 查看 Cookie 请求头。
• 通过 JavaScript 删除 Cookie 未成功：该 Cookie 为 HttpOnly，或需要匹配 Path 和 Domain 参数。使用 new_page 创建一个新的 isolatedContext，以获得干净的环境。
• 响应中设置了 Cookie，但请求未发送该 Cookie：
  • 确认页面是否使用 http://，而 Cookie 是否指定了 Secure。
  • 检查 Domain 是否限制了子域名。
  • 检查 list_console_messages(types: ["issue"])，查看浏览器拒绝 Cookie 的原因。
• 残留 Cookie 污染审计结果：运行合规测试时，始终使用带有唯一 isolatedContext 的 new_page，并在完成后调用 close_page。