alreshi/1password-cookies

1Password 工作階段 Cookie

適用於已驗證瀏覽器工作階段的操作手冊，其 Cookie 儲存在 1Password 中，而非 Git 儲存庫。在編寫 Cookie 同步、擷取或注入程式碼前，請先閱讀此文件。項目結構、Chrome 對應及疑難排解請參閱：references/REFERENCE.md。

此技能是一個工作階段 Cookie 工作流程。它與 1Password Environments MCP（.env 掛載）不同。請勿將 Cookie JSON 儲存為環境變數。

完成條件

推送上傳 (JSON → 1Password)

• Cookie 使用 Get cookies.txt LOCALLY 以 JSON 格式匯出（非 Netscape .txt）
• Cookie JSON 檔案已加入 .gitignore
• op 已登入且儲存庫存在
• 透過 --template 建立或更新項目（絕不將機密值作為命令列參數）
• 記錄摘要（數量、區段名稱、代號是否存在）

擷取 (應用程式 / 代理執行時期)

• OP_SERVICE_ACCOUNT_TOKEN 來自環境變數，絕不寫死
• 每個 Cookie 欄位解析為完整的 Cookie 物件 JSON，並提供純值備用方案
• 日誌顯示數量 / 主機名稱 / 代號是否存在 — 絕不顯示實際值

注入 (瀏覽器)

• Cookie 按原始來源分組；在 setCookie 前頁面先導航至該原始來源
• sameSite、domain / hostOnly、secure 已對應（參閱 references/REFERENCE.md）
• Chrome 拒絕的 Cookie 會跳過；登入驗證透過 URL / 標題進行，不傾印 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 時將其視為純字串（domain/path/expiry 必須保留）

架構

1. 人類使用者從 Chrome 以 Get cookies.txt LOCALLY 匯出 Cookie，格式為 Cookie 物件的 JSON 陣列。
2. 命令列 (op item create|edit --template) 使用一個 API_CREDENTIAL 項目進行新增或更新。每個 Cookie 是一個隱藏欄位，其值為完整的 Cookie 物件 JSON。
3. 無人值守應用程式使用 @1password/sdk 及服務帳號代號進行擷取。
4. 瀏覽器自動化程式依原始來源注入 Cookie，然後選擇性地將存取代號寫入 localStorage / sessionStorage。

互動式 op 適用於人類（及已登入命令列的代理）。服務帳號 SDK 適用於機器人及爬蟲。

新專案檢查清單

在編寫程式碼前，請複製此清單並填寫：

- [ ] 儲存庫名稱
- [ ] 項目標題（非 Service Account Auth Token 項目）
- [ ] 每個原始來源的 JSON 匯出路徑（來自 Get cookies.txt LOCALLY，已加入 .gitignore）
- [ ] 每個 JSON 檔案的區段 ID 與標籤
- [ ] 原始來源 URL 對應（Cookie domain 後綴 → 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. 將匯出格式設為 JSON — 非 Netscape (.txt) 也非 Header String。
4. 針對目前網站按一下匯出。只有在必要時才使用匯出所有 Cookie，之後再按原始來源拆分檔案。
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 為檔名主體的 slug，標籤為檔名。

--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 儲存庫視為唯一真實來源。