Aller au contenu

Profils, synchronisation des cookies, secrets et 2FA

La plupart des tâches qui valent la peine d’être automatisées se trouvent derrière une connexion. Il existe trois façons de connecter un navigateur hébergé sans mettre de mot de passe dans votre code : vous connecter une fois et garder la session dans un profil, y copier des cookies que vous avez déjà avec la synchronisation des cookies, ou laisser une exécution d’agent saisir les identifiants à partir de secrets que le modèle ne voit jamais, codes 2FA compris.

Profils

Un profil conserve les cookies, le localStorage et l’IndexedDB d’une session sous un nom. Démarrez une session avec profile: { name: "shop-account", persist: true } pour le charger et le réenregistrer à la fin de la session, ou avec profile: "shop-account" pour le charger en lecture seule. Sauf si vous passez identity ou fingerprint, un profil apporte aussi sa propre identité : le même appareil, et la même IP résidentielle tant que cette IP reste en ligne. Toutes les règles se trouvent dans Profils : se connecter une seule fois ; depuis le SDK, voir un contexte persistant sur un profil cloud.

Pour voir ce que contient un profil, sans ses valeurs :

bash
curl -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers/profiles/shop-account
# {
#   "name": "shop-account",
#   "cookies": 42,
#   "domains": ["example.com", "shop.example.com"],
#   "bytes": 18211,
#   "storage": "Local Storage,IndexedDB",
#   "updatedAt": "2026-10-02T09:20:11.000Z"
# }

domains liste jusqu’à 50 sites, triés, sans point initial. bytes est la taille compressée. storage nomme le stockage de site enregistré avec lui (Local Storage, IndexedDB) ; il est vide pour un profil qui ne contient que des cookies importés. Un nom inconnu renvoie 404 NOT_FOUND.

Aucun endpoint ne renvoie la valeur d’un cookie. Le contenu d’un profil n’est ouvert que sur nos serveurs : pour fusionner un import, pour compter ce qu’il contient, et sur le serveur qui exécute une session dessus.

Si vous êtes déjà connecté quelque part (votre propre navigateur, un Clearcote local, un script Playwright), copiez ces cookies dans un profil cloud et chaque session sur ce profil démarre connectée :

bash
curl -X PUT https://www.clearcotelabs.com/api/v1/browsers/profiles/shop-account/cookies \
  -H "authorization: Bearer cc_live_..." -H "content-type: application/json" \
  -d '{
    "mode": "merge",
    "cookies": [
      { "name": "session_id", "value": "…", "domain": "shop.example.com", "path": "/",
        "secure": true, "httpOnly": true, "sameSite": "Lax", "expires": 1798761600 }
    ]
  }'
# { "name": "shop-account", "cookies": 42, "imported": 1, "domains": ["example.com", "shop.example.com"],
#   "bytes": 18211, "updatedAt": "…" }
  • Tous les formats de cookies courants. Le format CDP (Network.getCookies, Network.Cookie / CookieParam) et le format Playwright (context.cookies(), les cookies d’un fichier de storage state) fonctionnent tels quels ; une url peut remplacer domain. Sans expires, avec expires: -1 (toute valeur jusqu’à 0) ou session: true, c’est un cookie de session, et un cookie déjà expiré est ignoré. sameSite vaut Lax, Strict ou None, quelle que soit la casse, et None exige secure: true.
  • Vérifiés comme Chrome les vérifie. Un cookie que Chrome refuserait (un ; dans une valeur, sameSite: "None" sans secure, un cookie __Secure- ou __Host- qui enfreint ses règles, un chemin qui ne commence pas par /) fait de tout l’import un 400 dont le message le nomme.
  • Enregistrés sous la forme name, value, domain (en minuscules), path (/ par défaut), secure, httpOnly, sameSite (seulement si vous l’avez envoyé) et expires (absent pour un cookie de session). Les autres champs, comme partitionKey, sont abandonnés.
  • mode: "merge" (par défaut) ajoute vos cookies et remplace ceux qui ont le même nom, le même domaine et le même chemin. mode: "replace" fait des cookies du profil exactement la liste que vous envoyez. Dans les deux cas, le localStorage et l’IndexedDB du profil sont conservés.
  • Limites : 5000 cookies au maximum par requête, et 5000 dans le profil après une fusion (400 TOO_MANY) ; noms jusqu’à 256 caractères, valeurs jusqu’à 4096, chemins jusqu’à 1024 ; le profil entier, 3.5 MB compressé au maximum (413 TOO_LARGE) ; 60 imports par tranche de 10 minutes.
  • Un profil qui n’existe pas encore est créé. Tant qu’une session qui enregistre dans le profil (persist: true) démarre ou tourne, un import est refusé avec 409 PROFILE_IN_USE : la session l’écraserait en se terminant.
  • Les cookies de session importés (sans expiration) sont chargés dans les sessions suivantes comme les autres. Une session qui enregistre le profil les abandonne, comme le fait un vrai navigateur au redémarrage : importez-les à nouveau si vous en avez besoin après cela.

La réponse indique le nombre de cookies du profil après l’import (cookies) et combien des vôtres ont été repris (imported : les cookies expirés et les doublons sont exclus), et liste les 50 premiers de ses domaines, triés.

Depuis votre machine, avec le SDK

La commande clearcote lit les cookies là où vous les avez et n’envoie que les domaines que vous indiquez :

bash
# a local Clearcote profile folder (the user_data_dir of launch_persistent_context)
clearcote cloud profile sync shop-account --from-profile ./profiles/shop --domain example.com

# a browser that is running with a CDP endpoint, for example clearcote serve
clearcote cloud profile sync shop-account --from-cdp http://127.0.0.1:9222 --domain example.com

# a Playwright storage-state file: context.storage_state(path="state.json")
clearcote cloud profile sync shop-account --from-file state.json --domain example.com --domain example-cdn.net

# sign in by hand: opens a local Clearcote window on a throwaway profile at the URL,
# you sign in and press Enter, and the cookies for the chosen domains are uploaded
clearcote cloud profile sync shop-account --login https://shop.example.com/login --domain example.com
  • --domain (à répéter pour plusieurs) sélectionne les cookies qu’un navigateur enverrait à ce domaine : les siens, ceux de ses sous-domaines et ceux de ses domaines parents (--domain shop.example.com prend aussi les cookies .example.com, jamais ceux posés sur un simple suffixe comme .com). Sans --domain ni --all-domains, la commande refuse de s’exécuter, pour que rien n’envoie par accident tous les cookies d’un profil.
  • --all-domains envoie tout. Ne l’utilisez que pour un profil créé pour cette seule tâche.
  • --replace envoie mode: "replace" ; par défaut, les cookies sont fusionnés.
  • Dans le code, profiles.sync(name, …) accepte les mêmes choix : exactement un parmi from_profile, from_cdp, from_file ou login_url (Node : fromProfile, fromCdp, fromFile, loginUrl), puis domains=[…] ou all_domains=True (allDomains: true), et replace=True. Elle renvoie la réponse d’import décrite plus haut, et lève ValueError (une Error en Node) sans rien envoyer quand aucun cookie ne correspond.
from clearcote import launch_persistent_context
from clearcote.cloud import Cloud

cloud = Cloud()

# the same as the command line
cloud.profiles.sync("shop-account", from_file="state.json", domains=["example.com"])

# or upload cookies you have in hand, here from a local profile you signed in with
# (cloud=False: this folder is on your machine, whatever CLEARCOTE_CLOUD says)
ctx = launch_persistent_context("./profiles/shop", cloud=False)
cookies = ctx.cookies("https://shop.example.com")       # only this site's cookies
ctx.close()
cloud.profiles.import_cookies("shop-account", cookies)  # mode="merge"

Tant qu’il est valide, un cookie vaut un mot de passe : quiconque détient un cookie de session est connecté en votre nom. N’envoyez que les domaines dont la tâche a besoin, rien de plus. Certains sites lient une connexion à l’appareil ou à l’IP d’où elle a été faite et déconnectent un cookie copié ; pour ceux-là, connectez-vous plutôt une fois dans une session hébergée avec persist: true.

Secrets et 2FA

Une exécution d’agent peut saisir des valeurs que le modèle ne voit jamais : mots de passe, numéros de compte et le code en cours d’un authentificateur TOTP. Placez-les dans secrets et faites-y référence dans la tâche avec {{name}} :

import os
from clearcote.cloud import Cloud

run = Cloud().runs.create(
    "Sign in with {{email}} and {{password}}. If a code is asked for, enter {{otp}}. "
    "Then open Orders and read the number of the latest order.",
    url="https://shop.example.com/login",
    secrets={
        "email": "me@example.com",
        "password": {"value": os.environ["SHOP_PASSWORD"]},
        "otp": {"totp": os.environ["SHOP_TOTP_SECRET"]},
    },
    schema={"type": "object", "properties": {"order": {"type": "string"}}, "required": ["order"]},
    profile={"name": "shop-account", "persist": True},   # next time it starts signed in
)
print(run["status"], run["result"]["output"])
Cet onglet s’exécute sur votre machine.
ChampTypeSignification
"name": "value"stringUne valeur simple, saisie sur l’hôte de l’url de l’exécution (et ses sous-domaines).
valuestringLa valeur, de 1 à 1024 caractères.
totpbase32 stringUn secret 2FA à la place d’une valeur : la clé de configuration affichée à côté du QR code (lettres A–Z et chiffres 2–7, 128 au maximum ; espaces et minuscules acceptés). L’exécution saisit le code en cours.
digits6 | 8TOTP uniquement. 6 par défaut.
period30 | 60TOTP uniquement, en secondes. 30 par défaut.
domainsstring[]Les hôtes sur lesquels il peut être saisi : 1 à 10 noms d’hôte comme example.com (au moins deux labels ; ni schéma, ni chemin, ni port, ni *), chacun avec ses sous-domaines. Par défaut : l’hôte de url.
  • Un secret est une chaîne, { value, domains? } ou { totp, domains?, digits?, period? }. 20 au maximum par exécution. Les noms commencent par une lettre et contiennent des lettres, des chiffres et _, jusqu’à 32 caractères.
  • Un {{name}} dans la tâche qui ne figure pas dans secrets donne un 400 (unknown secret "name"). De même pour un secret sans domains dans une exécution sans url : il n’y a aucun hôte auquel le lier. Écrivez la référence exactement sous la forme {{name}}, sans espaces.
  • Un secret que la tâche ne mentionne jamais est accepté ; les warnings de la réponse de création le signalent.
  • Attention à l’hôte. Par défaut, un secret est lié à l’hôte de url et à ses sous-domaines : https://shop.example.com/login couvre shop.example.com, pas login.example.com. Si le formulaire de connexion se trouve sur un autre hôte (authentification unique, fournisseur d’identité), indiquez-le dans domains.
  • Les codes TOTP suivent la RFC 6238 avec SHA-1, ce qu’utilisent les applications d’authentification. Le code est calculé au moment où il est saisi : c’est donc toujours le code en cours.
  • Les secrets appartiennent à une seule exécution. Ils ne sont pas enregistrés avec un profil et ne sont pas conservés après l’exécution : renvoyez-les avec la suivante (ou lancez la suivante sur un profil connecté et sautez la connexion).

Ce que voit le modèle

Avant le démarrage de Jet, chaque {{name}} de la tâche est remplacé par un espace réservé aléatoire comme CCSECRET_password_k3x9qa, et la tâche reçoit une phrase indiquant que les espaces réservés doivent être saisis exactement tels qu’ils sont écrits. C’est tout ce que le modèle reçoit. Quand Jet saisit un espace réservé, la couche navigateur du serveur y substitue à ce moment-là la vraie valeur, ou le code TOTP en cours, et seulement si l’hôte de la page fait partie des domains du secret ou est un sous-domaine de l’un d’eux (pour un champ dans une iframe, l’hôte du frame aussi). Sur tout autre hôte, l’étape s’arrête avec needs_input (« secret password is not allowed on other.example ») et rien n’est saisi.

Tout ce qui revient est nettoyé de la même façon : dans detail, markdown, le text de chaque étape, le JSON output et les événements, la valeur d’un secret, son code TOTP en cours et son espace réservé apparaissent sous la forme {{name}}. Une conséquence : si la page affiche un secret (par exemple l’adresse e-mail après la connexion) et que votre schéma la demande, vous obtenez {{email}}, pas l’adresse.

Modèle de sécurité

Ce qui protège quoi, et où sont les limites :

  1. Votre clé d’API, c’est votre compte. Elle permet de démarrer des navigateurs sur votre solde, d’utiliser vos profils et de lire vos exécutions. Gardez-la sur un serveur, jamais dans un navigateur ni dans une application que vous distribuez.
  2. Les profils sont privés et chiffrés. Chacun est stocké chiffré (AES-256-GCM, avec une clé par client) et ouvert uniquement sur nos serveurs : pour fusionner un import, pour compter ce qu’il contient, et sur le serveur qui exécute une session dessus. Le profil d’un autre client portant le même nom est un autre profil. Aucun endpoint ne renvoie la valeur d’un cookie (une session sur le profil peut bien sûr lire ses propres cookies via CDP).
  3. La synchronisation des cookies envoie ce que vous choisissez. Vous seul pouvez importer dans vos profils, dans les limites ci-dessus (5000 cookies, 3.5 MB), et jamais dans un profil qu’une session en démarrage ou en cours est en train d’enregistrer. Le choix des domaines se fait de votre côté : clearcote cloud profile sync et profiles.sync() refusent d’envoyer tout un jeu de cookies sauf si vous passez --all-domains / all_domains=True.
  4. Les secrets restent scellés jusqu’au démarrage de l’exécution. Ils sont stockés chiffrés de la même façon, dans les paramètres de l’exécution, et ouverts uniquement quand un serveur prend en charge l’exécution. Ils sont remis une seule fois à ce serveur, et les paramètres stockés sont effacés à ce moment-là. Sur le serveur, ils restent en mémoire et parviennent au processus Jet par son entrée standard : jamais dans des variables d’environnement, des lignes de commande, des logs ou des événements. S’ils ne peuvent plus être ouverts quand un serveur prend l’exécution en charge, celle-ci se termine en failed avec session.endReason secrets_unreadable.
  5. Le modèle ne reçoit jamais de secret. Il travaille avec des espaces réservés, et la vraie valeur n’est saisie que sur les hôtes que vous avez autorisés. Une page qui tente de persuader l’agent de saisir votre mot de passe ailleurs (prompt injection) obtient une étape refusée, pas le mot de passe.
  6. Les sorties sont expurgées. Les valeurs, les codes TOTP et les espaces réservés sont remplacés par {{name}} dans tout ce qu’une exécution renvoie ou stocke.
  7. Jet tourne à l’écart des identifiants du serveur. Chaque exécution est un processus distinct avec un environnement explicite et minimal : les clés du serveur et les identifiants du proxy ne lui sont jamais transmis, ni au navigateur. Le navigateur garde les protections de l’hébergement : pas de fichiers locaux, pas de réseaux privés.

Et ce que cela ne couvre pas :

  • Le site auquel vous vous connectez reçoit la valeur. C’est le but ; choisissez domains avec soin.
  • La page peut l’afficher. Une fois une valeur saisie dans un champ ordinaire, la page l’affiche. Jet remplace une valeur saisie par son espace réservé avant que le modèle ne lise la page, mais seulement là où elle apparaît exactement telle que saisie (ou encodée pour une URL) : une page qui l’affiche modifiée, par exemple reformatée ou partiellement masquée, n’est pas interceptée. Les champs de mot de passe ne sont jamais lus.
  • Les enregistrements montrent l’écran. Une valeur dans un champ ordinaire apparaît dans la vidéo. Laissez record désactivé pour les connexions que vous ne voulez pas voir archivées.
  • La tâche n’est pas secrète. Elle est stockée avec l’exécution et affichée dans le tableau de bord et dans la liste des exécutions. N’écrivez jamais une valeur dans la tâche elle-même ; utilisez toujours {{name}}.
  • Les liens sont des clés. Un lien de passage de relais ou de contrôle permet à quiconque le possède de piloter le navigateur, connecté, jusqu’à son expiration. Ne l’envoyez qu’à la personne qui doit agir.

Mis à jour le 5 oct. 2026 · SDK 0.70.5 · navigateur r63

Cette page vous a-t-elle été utile ?