alreshi/1password-cookies

1Password-Sitzungscookies

Playbook für authentifizierte Browser-Sitzungen, deren Cookies in 1Password leben, nicht in Git. Lesen Sie dies, bevor Sie Code zum Synchronisieren, Abrufen oder Einfügen von Cookies schreiben. Itemschema, Chrome-Zuordnung und Fehlerbehebung: references/REFERENCE.md.

Diese Fähigkeit ist ein Sitzungscookie-Workflow. Es handelt sich nicht um den 1Password Environments MCP (.env-Einhängungen). Speichern Sie Cookie-JSON nicht als Umgebungsvariablen.

Nicht erledigt, bis

Push (JSON → 1Password)

• Cookies exportiert mit Get cookies.txt LOCALLY als JSON (nicht Netscape .txt)
• Cookie-JSON-Dateien sind in .gitignore
• op ist angemeldet und der Tresor existiert
• Item erstellt oder aktualisiert über --template (niemals geheime Werte auf argv)
• Zusammenfassung protokolliert (Anzahl, Abschnittsnamen, Token vorhanden/nicht vorhanden)

Abrufen (App / Agenten-Laufzeit)

• OP_SERVICE_ACCOUNT_TOKEN kommt aus der Umgebung, niemals hartcodiert
• Jedes Cookie-Feld als vollständiges Cookie-Objekt-JSON geparst, mit Fallback auf reinen Wert
• Logs zeigen Anzahl / Hostname / Token-vorhanden – niemals Werte

Einfügen (Browser)

• Cookies nach Herkunft gruppiert; Seite navigiert zu dieser Herkunft vor setCookie
• sameSite, domain / hostOnly, secure zugeordnet (siehe references/REFERENCE.md)
• Von Chrome abgelehnte Cookies werden übersprungen; Login wird nachgewiesen, ohne Cookies auszugeben

Nicht tun

• Cookie-JSON committen oder Cookie-/Token-/cookieHeader-Werte in den Chat einfügen
• Geheimnisse auf Prozess-argv setzen (op item edit … value=geheimnis)
• Items ändern, deren Titel Service Account Auth Token: … lauten
• Den 1Password Environments MCP oder .env-Einhängungen für Cookie-Sitzungen verwenden
• Set-Cookie, Authorization, access_token oder Feldwerte protokollieren
• Ein Cookie-Feld als einfachen String behandeln, wenn es JSON ist (Domain/Pfad/Ablauf müssen erhalten bleiben)

Architektur

1. Mensch exportiert Cookies aus Chrome mit Get cookies.txt LOCALLY als JSON-Array von Cookie-Objekten.
2. CLI (op item create|edit --template) legt einen API_CREDENTIAL-Eintrag an/aktualisiert ihn. Jedes Cookie ist ein verdecktes Feld, dessen Wert das gesamte Cookie-Objekt-JSON ist.
3. Unbeaufsichtigte Apps rufen mit @1password/sdk und einem Servicekonto-Token ab.
4. Browserautomatisierung injiziert Cookies pro Herkunft und schreibt optional ein Zugriffstoken in localStorage / sessionStorage.

Interaktives op ist für Menschen (und Agenten mit angemeldeter CLI). Servicekonto-SDK ist für Bots und Scraper.

Checkliste für neue Projekte

Kopieren Sie diese Liste und füllen Sie sie aus, bevor Sie Code schreiben:

- [ ] Tresorname
- [ ] Item-Titel (kein Service-Account-Auth-Token-Item)
- [ ] Ein JSON-Exportpfad pro Herkunft von Get cookies.txt LOCALLY (gitignoriert)
- [ ] Abschnitts-ID + Bezeichnung pro JSON-Datei
- [ ] Herkunfts-URL-Zuordnung (Cookie-Domain-Suffix → https://host/)
- [ ] Name der Umgebungsvariable für das Servicekonto-Token (Standard OP_SERVICE_ACCOUNT_TOKEN)
- [ ] Geschützte Item-Titel, die abgelehnt werden sollen

Dann:

1. Exportieren Sie Cookies mit Get cookies.txt LOCALLY als JSON. Fügen Sie diese Dateinamen zur .gitignore hinzu.
2. Pushen Sie mit scripts/sync-cookies.sh (kopieren Sie das Skript in das Projekt oder führen Sie es aus diesem Skill-Verzeichnis aus).
3. Kopieren Sie scripts/fetch-session.js in die App; setzen Sie OP_VAULT_ID / OP_ITEM_ID aus op item get --format json (id-Felder). Bevorzugen Sie Umgebungsvariablen gegenüber hartcodierten Werten.
4. Implementieren Sie das Einfügen mit der Zuordnung in references/REFERENCE.md. Weisen Sie das Login mit URL / Titel / „hat Login-Formular“ nach – nicht durch Ausdrucken von Cookies.

Cookies exportieren

Verwenden Sie die Chrome-Erweiterung Get cookies.txt LOCALLY (Quelle). Sie liest Cookies auf dem Gerät und sendet sie nicht vom Rechner.

1. Melden Sie sich in Chrome auf der Website an (und dem SSO-Host, falls die Sitzung über zwei Ursprünge geht).
2. Öffnen Sie Get cookies.txt LOCALLY auf diesem Tab.
3. Setzen Sie Export Format auf JSON – nicht Netscape (.txt) und nicht Header String.
4. Klicken Sie auf Export für die aktuelle Website. Verwenden Sie Export All Cookies nur, wenn es nötig ist, und teilen Sie die Datei dann nach Herkunft auf.
5. Speichern Sie die .json-Datei neben dem Toolkit (gitignoriert). Diese Datei ist die Eingabe für scripts/sync-cookies.sh --json.

Wiederholen Sie dies für jede Herkunft, für die Sie einen 1Password-Abschnitt benötigen. Netscape cookies.txt ist keine gültige --json-Eingabe.

Pushen

Erfordert op und python3. Werte werden durch eine temporäre Vorlage mit Modus 0600 geleitet, dann wird die Vorlage gelöscht.

bash scripts/sync-cookies.sh \
  --vault IhrTresor \
  --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 gilt für das vorherige --json. Wenn weggelassen, ist die Abschnitts-ID ein Slug des Dateinamensstamms und die Bezeichnung der Dateiname.

--dry-run zeigt eine Vorschau. --include-empty speichert leere Werte. --keep-missing behält Cookie-Felder, die aus dem JSON verschwunden sind.

Wenn der Titel bereits existiert, aktualisieren Sie dieses Item. Erstellen Sie kein zweites Item mit demselben Titel.

Abrufen

Laufzeit-Apps verwenden @1password/sdk, nicht op:

1. createClient({ auth: process.env.OP_SERVICE_ACCOUNT_TOKEN, integrationName, integrationVersion })
2. client.items.get(vaultId, itemId)
3. Sammeln Sie Felder nach sectionId (fügen Sie einen veralteten cookies-Abschnitt hinzu, falls vorhanden)
4. JSON.parse(field.value), wenn es wie ein Cookie-Objekt aussieht; sonst { name: field.title, value: raw }
5. Bauen Sie cookieHeader nur im Speicher auf. Geben Sie Anzahlen in Logs zurück.

Eingebaute Felder, die gelesen werden, wenn vorhanden: hostname, credential (Zugriffstoken), username.

Einfügen

Für jede Herkunftsgruppe: goto(origin) → setCookie(...). Wenn der Batch fehlschlägt, setzen Sie Cookies einzeln und überspringen Sie Fehlschläge.

SSO-Cookies zuerst, wenn die Website über SSO umleitet, dann die App-Herkunft, dann alle übrigen Herkünfte. Nachdem die Cookies gelandet sind, rufen Sie goto der App-Herkunft auf und injizieren Sie credential in localStorage / sessionStorage als access_token, wenn die App dies erwartet.

Sicherheit

• Chat und Logs: Namen, Anzahlen, Hostname, Booleans. Niemals Werte.
• Schlüssel redigieren, die cookie|access_token|authorization|password|credential|secret|set-cookie|cookieheader|bearer entsprechen.
• Servicekonto-Items sind schreibgeschützt. Cookie-Sync- und Secret-Push-Skripte müssen diese Titel ablehnen.
• Cookie-JSON auf der Festplatte ist eine aktive Sitzung. Halten Sie es gitignoriert; behandeln Sie den Tresor nach der Synchronisation als Quelle der Wahrheit.

Fehlerbehebung (Erweitert)

Zusätzlich zur Referenz in references/REFERENCE.md können Sie die folgenden Tests ausführen, um zu überprüfen, ob der Workflow korrekt funktioniert:

• Portabilität: Öffnen Sie die Seite in einem anderen Browser-Profil und prüfen Sie, ob die injizierten Cookies die Sitzung wiederherstellen.
• Ohne Token: Rufen Sie mit einem ungültigen oder fehlenden Servicekonto-Token ab – der Client sollte einen klaren Fehler werfen, keine Werte preisgeben.
• Abgelaufene Sitzung: Exportieren Sie Cookies nach dem Logout; das Einfügen sollte fehlschlagen. Bestätigen Sie, dass keine Werte durchsickern.
• Browser lehnt Cookie ab: Fügen Sie ein Cookie mit ungültigem sameSite oder domain ein. Das Skript sollte es überspringen und weitermachen.
• Doppelter Titel: Pushen Sie ein zweites Item mit demselben Titel. Das Skript sollte das vorhandene Item aktualisieren, kein neues erstellen.
• Schreibgeschütztes Item: Versuchen Sie, ein Item mit dem Titel Service Account Auth Token: … zu pushen. Das Skript sollte mit einem Fehler abbrechen.
• Zu viele Logs: Bei vielen Cookies (z. B. 500+) sollten Logs nur Zusammenfassungen enthalten, keine einzelnen Cookie-Werte.