| name | cookiecloud-sync |
| description | Sync browser cookies and LocalStorage into any project using the CookieCloud protocol. Fetches the end-to-end encrypted payload from a CookieCloud server, decrypts it (legacy CryptoJS or aes-128-cbc-fixed), and injects the session into Playwright, Puppeteer, Selenium, HTTP clients, or the project's existing login/session flow. Use when the user asks to sync cookies, restore a logged-in session, inject session cookies, 同步 Cookie / 注入登录态 / 读取会话, or whenever automation needs a logged-in browser context backed by a CookieCloud server. |
| license | GPL-3.0 |
| metadata | {"author":"easychen","repo":"https://github.com/easychen/CookieCloud","version":"1.0.0"} |
CookieCloud Agent Skill — Cookie Sync
You are an agent that implements the CookieCloud protocol. CookieCloud is a tool that syncs browser cookies and LocalStorage to a (self-hosted) server with end-to-end encryption. When the user asks you to sync cookies, restore a logged-in session, or inject session cookies into their current project, follow this spec.
1. Configuration — ask first, or read env
Three values are needed:
- COOKIE_CLOUD_HOST — server URL, e.g. https://ccc.ft07.com or self-hosted http://127.0.0.1:8088 (strip any trailing slash)
- COOKIE_CLOUD_UUID — UUID generated by the browser extension
- COOKIE_CLOUD_PASSWORD — encryption password
If environment variables with exactly these names already exist, use them. Otherwise ask the user for all three. Never guess or invent values.
2. Download the ciphertext
GET {HOST}/get/{UUID}
Response JSON: { "encrypted": "...", "crypto_type": "legacy" | "aes-128-cbc-fixed" }
3. Decrypt (locally, always)
Key material is the first 16 characters of the MD5(UUID + '-' + PASSWORD) hex digest.
- "legacy" (old default format): equivalent to CryptoJS.AES.decrypt(encrypted, key) with key passed as a string passphrase — OpenSSL EVP_BytesToKey (MD5, AES-256-CBC, PKCS7) with a "Salted__" wrapper. See CryptoJS docs / the CookieCloud README.
- "aes-128-cbc-fixed" (new format, preferred): standard AES-128-CBC. key = UTF-8 bytes of the 16 hex characters above; IV fixed to 16 zero bytes (00000000000000000000000000000000); PKCS7 padding; ciphertext is raw Base64 without the "Salted__" prefix.
Prefer the crypto_type returned by the server. JSON.parse the plaintext to get:
{ "cookie_data": { "example.com": [cookie, ...], ... }, "local_storage_data": { ... } }
4. Apply cookies to the current project
Flatten all cookie arrays in cookie_data into one list; if cookie.sameSite === 'unspecified', set it to 'Lax'. Then inject into the project's browser context / HTTP session:
- Playwright: browser.newContext() then context.addCookies(cookies)
- Puppeteer: page.setCookie(...cookies)
- Selenium: driver.add_cookie(cookie) for each cookie
- Node fetch/undici or Python requests: build the Cookie header from the serialized cookies
5. Implement for the current project's stack
- Node.js: fetch + crypto-js (node:crypto also works for aes-128-cbc-fixed). Reference: CookieCloud repo, examples/playwright.
- Python: PyCookieCloud (pip install pycookiecloud) or pycryptodome; note "legacy" is the EVP_BytesToKey format.
- Go / Rust / Java / PHP: implement the algorithm above; examples/fixediv has fixed-IV references.
- If the project already has login/session code, wrap "fetch → decrypt → inject" as an init helper and wire it into the existing flow so the rest of the code runs authenticated.
6. Security requirements
- The server only stores ciphertext; GET /get/:uuid needs no password, decryption happens locally.
- Never hardcode UUID/PASSWORD into source or commit them. Prefer environment variables or a .env file listed in .gitignore.
- When done, briefly report: which config sources you used, which files you created or changed, and how to run and verify the sync.
