Логины, секреты и профили

Агент может входить на сайты за вас так, что модель ни разу не увидит пароль. Вы один раз сохраняете каждую учётную запись в хранилище, привязав её к сайтам, где её можно использовать, и передаёте запуску её имя. Агент решает, куда подставить значение. Само значение расшифровывается и вводится только в этот момент и только если страница находится на разрешённом вами сайте.

Сохранение секрета в хранилище#

PUT /v1/browser/vault/{name} сохраняет секрет. Повторная отправка с тем же именем заменяет его.

curl -X PUT https://lovelyrouter.com/v1/browser/vault/shop_password \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "value": "correct-horse-battery-staple",
    "kind": "password",
    "origins": ["https://shop.example.com"]
  }'

Ответ подтверждает, что сохранено, без самого значения:

{ "name": "shop_password", "kind": "password", "origins": ["https://shop.example.com"], "stored": true }

Секреты доступны только для записи: ни один эндпоинт не возвращает значение. Управлять ими можно также в консоли, в разделе «Секреты и файлы». Примеры на Python и Node.js используют настройку API, H и headers из раздела Запуск первой задачи.

Разрешённые сайты (origins)#

Агент может ввести секрет, только если страница, на которой он находится, по данным браузера совпадает с одним из origins секрета:

• https://shop.example.com совпадает ровно с этим сайтом и только по https.
• https://*.example.com совпадает с example.com и всеми поддоменами, например login.example.com.

На любом другом сайте секрет агенту даже не предлагается. Если фишинговая страница-двойник запросит ваш логин, агент никак не сможет ввести туда значение.

Использование секретов в запуске#

Передайте имена в secrets. Запуск может использовать только перечисленные вами секреты.

curl https://lovelyrouter.com/v1/browser/runs \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "goal": "Sign in and tell me the status of my latest order.",
    "start_url": "https://shop.example.com/login",
    "secrets": ["shop_user", "shop_password"]
  }'

Трассировка показывает, какой секрет куда попал, но никогда не значение: action шага выглядит как secret:e4:shop_password. Имя, которого нет в вашем хранилище, возвращает 400 с Unknown vault secret(s): shop_pw. Store them with PUT /v1/browser/vault/{name}.

Коды двухфакторной аутентификации#

Для сайтов, использующих приложение-аутентификатор, сохраните TOTP-сид как секрет totp. Сид — это текст за QR-кодом, который вы сканируете при включении двухфакторного входа (часто показывается по ссылке вроде «не удаётся отсканировать код?»): 16 или больше символов из A–Z и 2–7. Пробелы и дефисы игнорируются.

curl -X PUT https://lovelyrouter.com/v1/browser/vault/github_totp \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"value": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP", "kind": "totp", "origins": ["https://github.com"]}'

Когда сайт запрашивает код, агент вводит текущий (стандартные 6-значные коды с периодом 30 секунд). Передайте имя сида в secrets вместе с именем пользователя и паролем.

Для кодов, приходящих по SMS или email, пусть агент спросит вас: он приостановится с вопросом, а вы ответите {"secret": "481923"}. См. Ответ на вопрос.

Секреты на один запуск#

Если вы не хотите хранить учётные данные — например, те, что ваши пользователи дают вам для одной задачи, — передайте их в ephemeral_secrets. Они работают как секреты из хранилища, но живут только в рамках запуска: хранятся в зашифрованном виде, пока запуск активен, и удаляются по его завершении.

{
  "goal": "Sign in and tell me the account's plan name.",
  "start_url": "https://app.example.com/login",
  "ephemeral_secrets": {
    "customer_email": { "value": "ada@example.com", "kind": "username", "origins": ["https://app.example.com"] },
    "customer_password": { "value": "s3cret-pa55word", "kind": "password", "origins": ["https://app.example.com"] }
  }
}

Имена подчиняются правилам хранилища и не должны повторять имена, которые вы также передаёте в secrets. kind по умолчанию равен password, а origins обязателен.

Учётные данные в цели#

Если сама цель содержит пароль («войди как demo / demo1234»), агент может ввести его в поле пароля. Это работает, но цель отправляется модели, возвращается в объекте запуска и хранится в истории ваших запусков. Используйте этот способ только для одноразовых тестовых аккаунтов. Для всего настоящего используйте секрет из хранилища или секрет на один запуск.

Сохранение и повторное использование сессии#

Профиль — это сохранённая сессия браузера: cookie и локальное хранилище сайтов, которые посетил запуск. Сохраните его после входа, и следующие запуски будут начинаться уже в аккаунте, без секретов и без запроса двухфакторного кода.

Сохраните профиль с помощью save_profile (имя до 64 символов):

{
  "goal": "Sign in to the shop and tell me my name as shown on the account page.",
  "start_url": "https://shop.example.com/login",
  "secrets": ["shop_user", "shop_password", "shop_totp"],
  "save_profile": "shop-login"
}

Когда запуск завершается, profile_saved в объекте запуска показывает, что было сохранено:

{ "profile_saved": { "id": "prof_4c1e9a7b2d0f3e5a8b6c", "name": "shop-login", "cookies": 14 } }

Начните с него следующий запуск через profile (имя или id профиля):

{
  "goal": "Open my orders and tell me the status of the latest one.",
  "start_url": "https://shop.example.com/account/orders",
  "profile": "shop-login"
}

• Сохранение под существующим именем обновляет этот профиль. Чтобы сессия оставалась свежей, передавайте одно и то же имя и в profile, и в save_profile.
• Профиль сохраняется при любом финальном статусе запуска.
• Сессии истекают по правилам сайта. Когда профиль перестаёт работать, снова выполните вход с save_profile. Если передать secrets вместе с profile, агент сможет сам войти заново, если сессия истекла.
• Неизвестный профиль возвращает 400 с Unknown profile "shop-login" (GET /v1/browser/profiles).
• Профиль содержит действующие cookie сессии. Обращайтесь с ним как с паролем и удаляйте те, что больше не нужны.

Управление секретами и профилями#

# List secrets: names, kinds, origins and dates, never values
curl https://lovelyrouter.com/v1/browser/vault -H "Authorization: Bearer $LOVELY_API_KEY"

# Delete a secret
curl -X DELETE https://lovelyrouter.com/v1/browser/vault/shop_password -H "Authorization: Bearer $LOVELY_API_KEY"

# List profiles
curl https://lovelyrouter.com/v1/browser/profiles -H "Authorization: Bearer $LOVELY_API_KEY"

# Delete a profile by name or id
curl -X DELETE https://lovelyrouter.com/v1/browser/profiles/shop-login -H "Authorization: Bearer $LOVELY_API_KEY"

У каждого секрета в списке есть last_used_at, так что видно, когда запуск вводил его в последний раз. Полные формы ответов приведены в справочнике API.

Как защищены ваши секреты#

• Шифрование при хранении. Секреты, секреты на один запуск, профили и загруженные файлы шифруются AES-256-GCM на ключах, выведенных отдельно для вашего аккаунта и для каждого запуска. Каждое значение привязано к своему владельцу и имени, поэтому его нельзя расшифровать как чужое или под другим именем.
• Только для записи. API никогда не возвращает значение секрета — ни вам, ни кому-либо с вашим ключом.
• Никогда не отправляются модели. Агент работает с именами вроде shop_password. Значение расшифровывается только в момент ввода, после проверки сайта страницы и типа поля.
• Вычищаются из вывода. Любое значение секрета длиной от шести символов, появившееся в тексте страницы, ответе, data или трассировке шагов, заменяется на [secret:<name>]. В точном режиме скриншоты прекращаются, как только введён секрет.
• Короткий срок жизни, если нужно. Секреты на один запуск и секретные ответы удаляются по завершении запуска.

Ваш API-ключ имеет доступ к хранилищу, поэтому защищайте его так же, как сами секреты. Ограничьте возможности ключа в разделе API-ключи и включите двухфакторный вход для своего аккаунта в разделе Безопасность аккаунта.