alreshi/1password-cookies

1Password セッションCookie

ブラウザ認証セッションのCookieを1Passwordで管理し、gitではなく1Passwordに保存するためのプレイブックです。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 がサインイン済みで、対象のVaultが存在すること
• --template 経由でアイテムを作成または更新していること（argvに秘密値を直接指定しない）
• サマリーをログ出力すること（件数、セクション名、トークンの有無のみ）

取得（アプリ / エージェントランタイム）

• OP_SERVICE_ACCOUNT_TOKEN は環境変数からのみ取得し、ハードコードしないこと
• 各Cookieフィールドは完全なCookieオブジェクトJSONとしてパースし、プレーン文字列のフォールバックを用意すること
• ログには件数 / ホスト名 / トークンの有無のみを出力すること — 値は出力しない

注入（ブラウザ）

• Cookieをオリジンごとにグループ化し、setCookie の前にそのオリジンへページ遷移すること
• sameSite、domain / hostOnly、secure をマッピングすること（references/REFERENCE.md 参照）
• Chromeが拒否するCookieはスキップし、Cookieダンプなしでログインが完了したことを確認すること

禁止事項

• Cookie JSONのコミット、Cookie / トークン / cookieHeader 値のチャットへの貼り付け
• プロセスargvへの秘密値の設定（op item edit … value=secret）
• タイトルが Service Account Auth Token: … のアイテムの編集
• Cookieセッションに対する1Password Environments MCPまたは .env マウントの使用
• Set-Cookie、Authorization、access_token、フィールド値のログ出力
• CookieフィールドをJSONとして扱わず、単なる文字列として扱うこと（ドメイン/パス/有効期限が維持されない）

アーキテクチャ

1. 人間がChrome拡張機能 Get cookies.txt LOCALLY でCookieをJSON 配列（Cookieオブジェクトの配列）としてエクスポートする。
2. CLI（op item create|edit --template）で 1つの API_CREDENTIAL アイテムをアップサートする。各Cookieは 秘匿 フィールドとして、値に Cookieオブジェクト全体のJSON を格納する。
3. 無人アプリは @1password/sdk とサービスアカウントトークンで取得する。
4. ブラウザ自動化はCookieを オリジンごとに 注入し、必要に応じて localStorage / sessionStorage にアクセストークンを書き込む。

対話型の op は人間（およびサインイン済みCLIを持つエージェント）向けです。サービスアカウントSDKはボットやスクレイパー向けです。

新規プロジェクトチェックリスト

コードを書く前にこのリストをコピーして埋めてください：

- [ ] Vault名
- [ ] アイテムタイトル（サービスアカウント認証トークンアイテムではないこと）
- [ ] Get cookies.txt LOCALLY からエクスポートした、オリジンごとのJSONファイルパス（gitignoreされていること）
- [ ] JSONファイルごとのセクションID + ラベル
- [ ] オリジンURLマップ（Cookieドメインサフィックス → https://host/）
- [ ] サービスアカウントトークンの環境変数名（デフォルトは OP_SERVICE_ACCOUNT_TOKEN）
- [ ] 編集を拒否する保護対象アイテムタイトル

その後：

1. Get cookies.txt LOCALLY でCookieをJSONとしてエクスポートする。それらのファイル名をgitignoreに追加する。
2. scripts/sync-cookies.sh でプッシュする（プロジェクトにコピーするか、このスキルディレクトリから実行する）。
3. scripts/fetch-session.js をアプリにコピーする。OP_VAULT_ID / OP_ITEM_ID は op item get --format json（id フィールド）の結果から設定する。ハードコードよりも環境変数を優先する。
4. references/REFERENCE.md のマッピングを使用して注入を実装する。ログインの確認はURL / タイトル / 「ログインフォームがあること」で行い、Cookieの出力では行わない。

Cookieのエクスポート

Chrome拡張機能 Get cookies.txt LOCALLY（ソース）を使用します。この拡張機能はデバイス上でCookieを読み取り、マシン外に送信しません。

1. Chromeで対象サイトにログインします（セッションが2つのオリジンにまたがる場合は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 への入力になります。

必要なオリジンごとに繰り返します。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フィールドを維持します。

タイトルがすでに存在する場合は、そのアイテムを 更新 します。同じタイトルの2つ目のアイテムを作成しないでください。

取得

ランタイムアプリは op ではなく @1password/sdk を使用します：

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を1つずつ設定し、失敗したものをスキップします。

サイトが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を維持し、同期後はVaultを信頼できる情報源として扱ってください。