alreshi/1password-cookies

1Password 会话 Cookie

用于认证浏览器会话的 Playbook，其 Cookie 保存在 1Password 中，而非 Git 中。在编写 Cookie 同步、获取或注入代码之前，请先阅读本文。条目模式、Chrome 映射和故障排除请参见：references/REFERENCE.md。

该技能是一个会话 Cookie工作流。它不同于 1Password Environments MCP（.env 挂载）。请勿将 Cookie JSON 存储为环境变量。

完成条件

推送（JSON → 1Password）

• 使用 Get cookies.txt LOCALLY 以 JSON（非 Netscape .txt）格式导出 Cookie
• Cookie JSON 文件已被 .gitignore 忽略
• op 已登录，且保险库已存在
• 通过 --template 创建或更新条目（切勿在命令行参数中传递机密值）
• 记录摘要（计数、节名称、仅显示令牌是否存在）

获取（应用/Agent 运行时）

• OP_SERVICE_ACCOUNT_TOKEN 来自环境变量，绝不硬编码
• 每个 Cookie 字段解析为完整的 Cookie 对象 JSON，并提供纯文本值兜底
• 日志显示计数/主机名/令牌是否存在——不显示实际值

注入（浏览器）

• Cookie 按来源分组；在调用 setCookie 之前页面导航到该来源
• 映射 sameSite、domain / hostOnly、secure（参见 references/REFERENCE.md）
• Chrome 拒绝的 Cookie 被跳过；通过验证登录状态而非导出 Cookie 来证明登录成功

禁止事项

• 提交 Cookie JSON，或将 Cookie/令牌/cookieHeader 值粘贴到聊天中
• 将机密放在进程命令行参数上（op item edit … value=secret）
• 修改标题为 Service Account Auth Token: … 的条目
• 使用 1Password Environments MCP 或 .env 挂载来处理 Cookie 会话
• 记录 Set-Cookie、Authorization、access_token 或字段值
• 将 Cookie 字段当作纯字符串处理（当它是 JSON 时，域/路径/过期时间必须保留）

架构

1. 用户通过 Get cookies.txt LOCALLY 从 Chrome 导出 Cookie，格式为 JSON 数组，每个元素是一个 Cookie 对象。
2. CLI（op item create|edit --template）更新一个 API_CREDENTIAL 条目。每个 Cookie 是一个隐藏字段，其值为完整 Cookie 对象 JSON。
3. 无人值守应用通过 @1password/sdk 和服务账户令牌获取 Cookie。
4. 浏览器自动化按来源注入 Cookie，然后可选地将访问令牌写入 localStorage / sessionStorage。

交互式 op 适用于人类（以及已登录 CLI 的 Agent）。服务账户 SDK 适用于机器人和爬虫。

新项目检查清单

复制此列表并在编写代码前填写：

- [ ] 保险库名称
- [ ] 条目标题（不能是服务账户认证令牌条目）
- [ ] 每个来源一个从 Get cookies.txt LOCALLY 导出的 JSON 文件路径（已 `.gitignore`）
- [ ] 每个 JSON 文件的节 ID 和标签
- [ ] 来源 URL 映射（Cookie 域后缀 → https://host/）
- [ ] 服务账户令牌环境变量名称（默认为 OP_SERVICE_ACCOUNT_TOKEN）
- [ ] 受保护的条目标题，拒绝操作

然后：

1. 使用 Get cookies.txt LOCALLY 以 JSON 格式导出 Cookie。将这些文件名加入 .gitignore。
2. 使用 scripts/sync-cookies.sh 推送（复制到项目中，或从该技能目录运行）。
3. 将 scripts/fetch-session.js 复制到应用中；从 op item get --format json 的 id 字段设置 OP_VAULT_ID / OP_ITEM_ID。优先使用环境变量而非硬编码。
4. 使用 references/REFERENCE.md 中的映射实现注入。通过 URL/标题/“是否存在登录表单”来验证登录——而不是通过打印 Cookie。

导出 Cookie

使用 Chrome 扩展 Get cookies.txt LOCALLY（源码）。它在设备本地读取 Cookie，不会将数据发送到远程。

1. 在 Chrome 中登录目标站点（如果会话跨越两个来源，还需登录 SSO 主机）。
2. 在该标签页上打开 Get cookies.txt LOCALLY。
3. 将 Export Format 设置为 JSON——不要选择 Netscape（.txt）或 Header String。
4. 点击 Export 导出当前站点。仅在必要时使用 Export All Cookies，然后按来源拆分文件。
5. 将 .json 文件保存在工具包旁边（已 .gitignore）。该文件是 scripts/sync-cookies.sh --json 的输入。

在每个需要 1Password 节的来源上重复此操作。Netscape 格式的 cookies.txt 不是有效的 --json 输入。

推送

需要 op 和 python3。值通过临时模板（权限 0600）传递，然后模板被删除。

bash scripts/sync-cookies.sh \
  --vault YourVault \
  --title "example.com cookies" \
  --hostname "example.com, sso.example.com" \
  --url https://example.com \
  --json ./example.com.json --section app:example.com \
  --json ./sso.example.com.json --section sso:sso.example.com

--section ID:LABEL 适用于前面的 --json。如果省略，节 ID 为文件名干（不含扩展名）的驼峰式变体，标签为文件名。

--dry-run 预览。--include-empty 存储空值。--keep-missing 保留在 JSON 中消失的 Cookie 字段。

如果标题已存在，则更新该条目。不要创建第二个具有相同标题的条目。

获取

运行时应用使用 @1password/sdk，而不是 op：

1. createClient({ auth: process.env.OP_SERVICE_ACCOUNT_TOKEN, integrationName, integrationVersion })
2. client.items.get(vaultId, itemId)
3. 按 sectionId 收集字段（如果存在旧的 cookies 节也一并包含）
4. 当字段看起来像 Cookie 对象时使用 JSON.parse(field.value)；否则使用 { name: field.title, value: raw }
5. 仅在内存中构建 cookieHeader。在日志中返回计数。

读取以下内置字段（如果存在）：hostname、credential（访问令牌）、username。

注入

对于每个来源组：goto(origin) → setCookie(...)。如果整批失败，则逐个设置 Cookie 并跳过失败项。

当站点通过 SSO 重定向时，先设置 SSO Cookie，然后是应用来源，最后是其他剩余来源。Cookie 设置完成后，goto 到应用来源，如果应用期望，则将 credential 注入到 localStorage / sessionStorage 作为 access_token。

安全

• 聊天和日志中：名称、计数、主机名、布尔值。绝不输出实际值。
• 对匹配 cookie|access_token|authorization|password|credential|secret|set-cookie|cookieheader|bearer 的键进行脱敏。
• 服务账户条目是写保护的。Cookie 同步和机密推送脚本必须拒绝这些标题。
• 磁盘上的 Cookie JSON 是活动会话。保持其被 .gitignore 忽略；同步后以 1Password 保险库作为真实来源。