Cookiecloud Sync

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.