Cookie Store API：异步 Cookie、change 事件与隐私边界
说明 Cookie Store API 的异步读写、change 事件和 Service Worker 可见性，并把 origin 与隐私边界写进验证流程。
BotBrowser Team
Cookie Store API 把 Cookie 读写变成 Promise 操作，并提供 change 事件。它不会把 Cookie 变成跨 origin 的共享状态，也不会绕过浏览器的 Secure、SameSite、HttpOnly、Domain 或 Path 规则。本文用一个自有站点的 control/candidate fixture 区分页面、Service Worker 和其他 origin 能看到的结果。
摘要
BotBrowser 可以用合成 Cookie 重放页面与 worker fixture，但不能改变浏览器 Cookie 政策或证明服务器账户状态。本文依据 WICG Cookie Store 规范和 MDN 实现文档说明浏览器知识边界。
API 是异步的，事件只是当前上下文的观察，worker 启动后必须重新协调状态。origin 和 Cookie 属性仍是控制边界。BotBrowser 支持声明 BrowserContext 中的合成 Cookie 重放，但明确不能绕过浏览器政策、读取 HttpOnly 或证明服务器账户。
目录（内容）
- 异步读写
- change 事件
- Service Worker 可见性
- 隐私边界
- 实际结论
异步操作
cookieStore.get()、getAll()、set() 与 delete() 返回 Promise。成功只表示当前上下文接受了这次请求，不代表下一个请求、另一个标签页或服务器一定能看到该值。先检查 window.cookieStore，再区分 unsupported、written、deleted 和 rejected。
操作失败应成为可见的产品状态，而不是被吞掉的异常。若浏览器没有 API，可使用范围相同的既有 fallback；fallback 不能扩大 Cookie 的作用域，也不能把 token 写入日志。Cookie 值不应进入分析事件、截图或错误文本。
Change events
cookieStore 的 change 事件报告当前上下文可见的 changed/deleted Cookie。它适合刷新派生 UI，不是网络 webhook、完整审计日志或服务器已收到 Cookie 的证明。事件到达后重新读取当前状态，不要把事件载荷当作永远有效的值。页面和 worker 都可能需要处理重复、延迟或错过的通知。
Service Worker 可见性
在支持的安全上下文中，Service Worker 可以使用相关 Cookie Store API，但可见性仍受注册范围和 origin 限制。它不能读取其他 origin，也不能因拥有 scope 就成为身份授权方。Worker 停止期间可能错过事件，因此激活时应重新读取状态；同时记录 worker 版本，避免把脚本更新误判为浏览器变化。
隐私边界
使用自有 HTTPS 页面和同 origin worker，从干净 profile 开始设置测试标记、读取、删除并刷新。记录浏览器版本、secure context、worker 注册、Cookie 属性和可见结果。把 API 缺失、属性过滤、事件到达、删除成功分别列出。HttpOnly Cookie 不应被脚本读取；成功读取也不能证明人的身份、同意或服务器端账户状态。
BotBrowser 的 --bot-cookies 可为声明的 BrowserContext 建立合成起始状态，但不能授予 Cookie Store API 权限、暴露 HttpOnly 值或改变 SameSite。更新浏览器、worker、登录流程或 Cookie 属性后重跑 fixture。
延伸阅读
参见 Storage Access API for Embedded Content 与 Cookie Management。
实际结论
保持操作异步，在 worker 启动时重新协调状态，并记录浏览器版本和 Cookie 属性；所有结果都只代表限定上下文中的浏览器观察。
决策表
| 问题 | 记录 | 不要推断 |
|---|---|---|
set() 是否成功 | 当前 origin 接受了变更 | 服务器持久化或身份 |
是否收到 change | 合格上下文观察到变化 | 完整审计记录 |
| worker 是否读取标记 | worker 生命周期与 scope | 其他 origin 访问 |
| 删除后是否为空 | 当前上下文不再看到标记 | 所有备份都已删除 |