Перейти к основному содержимому

Попробуйте API разработчика расширений

Воспользуйтесь этим руководством, если хотите создать расширение Chastify, разместить страницу расширения в iframe или вызвать API разработчика из собственного бэкэнда.

Эта страница — отправная точка: какой режим выбрать, с чего начать звонок и куда двигаться дальше.

Для получения подробной информации о поведении расширений, таком как разблокировка блокировщиков, обязательные действия, награды и наказания, см. Функции API расширений.

подсказка

Хотите просто управлять своим замком?

Если вам не нужно создавать общедоступное расширение, страница Внешний API и программы — это самый простой способ начать. Вам просто нужно создать токен DEV и вызывать простые REST-конечные точки — никакой настройки расширения, никаких iframe, никакого управления сессиями не требуется. Поддерживается добавление/удаление времени, заморозка, задачи, команды для устройств и многое другое.

Для чего нужен этот API​

API для разработчиков расширений позволяет создавать сторонние расширения, работающие внутри сеансов блокировки Chastify.

С его помощью вы можете:

  • Чтение контекста сессии и блокировки (session.get для расширений, /api/apps/v1/session для вашей собственной автоматизации блокировки)
  • Считывайте данные, принадлежащие расширению, за каждую сессию блокировки (state.get) и записывайте их из вашего бэкэнда (PUT/PATCH /state).
  • Храните принадлежащие расширению файлы изображений в управляемом хранилище R2 (files.*) с помощью Chastify.
  • Добавить дополнительные действия пользовательского интерфейса на карточки блокировки (metadata.homeActions)
  • Процесс разблокировки ворот с использованием блокировщиков разблокировки, принадлежащих расширению (metadata.unlockBlockers)
  • Запуск блокировок из доверенного бэкэнда (добавление/удаление времени, заморозка/разморозка, изменение настроек).
  • Запуск задач и гигиенических действий (task.assign, task.start_timer, task.complete, hygienic_unlock.start)
  • Регулярно отправляйте отчеты о выполненных действиях с поддержкой счетчиков/регулярного выполнения.
  • Отправляйте команды для поддерживаемых устройств, когда они доступны.
  • Напишите пользовательские записи в журнале расширений для блокировки истории.

Что вы можете построить​

Правильный набор функций зависит от того, где находится доверие.

Расширения iframe, предназначенные только для фронтенда, позволяют создавать интерфейсы, ориентированные на пользовательский опыт, которые не требуют изменения доверенной блокировки:

  • Страницы настроек, которые собирают конфигурацию расширений.
  • Панели мониторинга, считывающие контекст сессии.
  • Пользовательские интерфейсы для головоломок, контрольных списков или игр, которые считывают состояние сессии и отправляют подтвержденный прогресс через бэкэнд.
  • Потоки обработки медиафайлов, считывающие файлы расширений, уже сохраненные Chastify.
  • Точки входа для действий на главной странице, которые открывают ваш iframe с помощью Intent.

Расширения, работающие на стороне сервера, могут создавать функции, влияющие на блокировки, поскольку ваш бэкэнд проверяет результаты перед вызовом привилегированных API:

  • Системы задач или привычек с требованиями к разблокировке
  • Ежедневные или еженедельные требования с запланированными наказаниями за пропущенные периоды.
  • Игры, в которых успех вознаграждается, а неудача наказывается изменением времени блокировки.
  • Процессы проверки, устраняющие препятствия после проверки на стороне сервера.
  • Последовательности действий по управлению устройством с использованием поддерживаемых команд устройства.
  • Рабочие процессы веб-перехватчиков/баз данных, которые сохраняют состояние расширения вне iframe.

Внешние программы предназначены для автоматизации работы вашего собственного активного замка:

  • Локальные скрипты
  • Персональные панели управления
  • Инструменты автоматизации, использующие ключ DEV, доступный для всех пользователей.

Выберите режим​

Выберите один из следующих режимов:

  1. Hosted iframe extension: разместите статический iframe-интерфейс на Cloudflare Pages или аналогичном сервисе. Используйте мост для настройки, контекста сессии и безопасного чтения. Не используйте этот режим отдельно для записи состояния, наград, наказаний, завершения разблокировки или отслеживания прогресса выполнения доверенных требований.
  2. Server-backed extension: разместите пользовательский интерфейс iframe и запустите собственный бэкэнд. iframe отправляет свой код запуска mainToken вашему бэкэнду, а ваш бэкэнд вызывает API расширения Chastify с ключом API разработчика, ограниченным областью действия приложения, плюс x-chastify-main-token. Используйте этот режим для привилегированных действий, разблокировки блокировщиков, доверенного прогресса, наград, наказаний, веб-хуков и внешних баз данных.
  3. External API & Programs: используйте универсальный ключ DEV для скриптов, локальных программ или автоматизации, управляющих вашей собственной активной блокировкой. Этот режим не подходит для сторонних пользователей, устанавливающих ваше расширение.

Если вы проводите быстрое тестирование, начните с режима iframe для пользовательского интерфейса и безопасного чтения. Добавьте бэкэнд до реализации записи состояния, доверенных вознаграждений, изменений времени, отслеживания выполнения запланированных требований или завершения блокировки разблокировки.

предупреждение

Код iframe не является границей доверия. Все, что видно iframe, включая хэш-данные и токены запуска, может быть проверено и воспроизведено пользователем.

Первые 10 минут (режим iframe)​

  1. Прочитать полезную нагрузку location.hash из открытого iframe Chastify.
  2. Создайте запрос на подключение для session.get.
  3. Подтвердите ответ с помощью type: "chastify:ext:resp" и ok: true.
  4. Состояние теста считывается с кодом state.get.
  5. Добавлена ​​поддержка автоматического изменения размера и тем оформления, чтобы iframe корректно отображался в пользовательском интерфейсе.

Поддержка тем оформления является частью готового к использованию iframe. Chastify передает значения ui в хэше запуска и отправляет обновления темы в реальном времени, пока iframe открыт. См. Iframe Theming для примеров светлой/темной темы и шаблонов Tailwind, обеспечивающих безопасность по контрасту.

Требуемые значения полезной нагрузки:

  • bridge.nonce
  • bridge.parentOrigin
  • sessionId
  • lockId

Пример запроса на создание моста:

{
  "type": "chastify:ext:req",
  "v": 1,
  "id": "request-id", // unique id per request
  "nonce": "nonce-from-hash",
  "action": "session.get",
  "payload": {}
}

Пример ответа моста:

{
  "type": "chastify:ext:resp",
  "v": 1,
  "id": "request-id",
  "ok": true,
  "data": {}
}

Основные действия, которые следует изучить в первую очередь​

  • session.get
  • state.get
    Считывайте данные из JSON-хранилища, принадлежащего расширению, для сессии блокировки. Записывайте состояние из вашего бэкэнда, используя учетные данные Developer API.
  • files.capabilities, files.list, files.get Используйте чтение из файлового хранилища для бинарных медиафайлов, таких как изображения-головоломки или сгенерированные предварительные просмотры. Сохраняйте идентификаторы файлов в состоянии, записанном на бэкэнде, а затем обновляйте подписанные URL-адреса с помощью files.get.
  • metadata.get Читайте блокировщики блокировки сеансов и действия/намерения на главной странице карточек расширений.
  • regularActions.get

Изменения сессии, такие как запись состояния, отправка обычных действий, загрузка/удаление файлов во время выполнения, изменение времени, обновление блокировщиков разблокировки, завершение задач, запуск очистки и команды устройства, должны вызываться из вашей серверной части с использованием ключа API разработчика. Код iframe браузера не считается надежным для этих действий.

Полный список поддерживаемых URL-адресов API​

Базовый домен: https://chastify.net

API-интерфейсы сессий расширений (/api/extensions/*)​

Эти маршруты имеют разные режимы доступа. Не следует рассматривать всю поверхность /api/extensions/* как безопасную для iframe.

Безопасные маршруты моста iframe проходят через родительский узел Chastify после запросов моста postMessage:

  • GET https://chastify.net/api/extensions/sessions/:sessionId
  • GET https://chastify.net/api/extensions/sessions/:sessionId/state
  • GET https://chastify.net/api/extensions/sessions/:sessionId/metadata
  • GET https://chastify.net/api/extensions/sessions/:sessionId/regular-actions
  • GET https://chastify.net/api/extensions/sessions/:sessionId/files/capabilities
  • GET https://chastify.net/api/extensions/sessions/:sessionId/files
  • GET https://chastify.net/api/extensions/sessions/:sessionId/files/:fileId

Для маршрутов, доступных только на бэкэнде и использующих установленные расширения, требуется ключ API разработчика с областью действия приложения и токен запуска iframe:

Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEY
x-chastify-main-token: MAIN_TOKEN_FROM_IFRAME_HASH
к сведению

Эта двухтокенная модель связывает запрос к бэкэнду как с разработчиком расширения (Authorization), так и с текущей открытой сессией расширения (x-chastify-main-token).

  • PATCH https://chastify.net/api/extensions/sessions/:sessionId/metadata
  • PUT https://chastify.net/api/extensions/sessions/:sessionId/state
  • PATCH https://chastify.net/api/extensions/sessions/:sessionId/state
  • PATCH https://chastify.net/api/extensions/sessions/:sessionId/regular-actions/config
  • POST https://chastify.net/api/extensions/sessions/:sessionId/regular-actions
  • POST https://chastify.net/api/extensions/sessions/:sessionId/files
  • DELETE https://chastify.net/api/extensions/sessions/:sessionId/files/:fileId
  • POST https://chastify.net/api/extensions/sessions/:sessionId/logs/custom
  • POST https://chastify.net/api/extensions/sessions/:sessionId/notifications/custom
  • POST https://chastify.net/api/extensions/sessions/:sessionId/device-command
  • POST https://chastify.net/api/extensions/sessions/:sessionId/action
  • POST https://chastify.net/api/extensions/sessions/:sessionId/requirements/progress

API для работы с токенами на стороне бэкэнда (/api/apps/v1/*)​

Используйте Authorization: Bearer <user-wide DEV token>. Эти конечные точки управляют активными сессиями блокировки владельца токена и предназначены для внешних API-скриптов/программ, а не для установленных сторонних расширений.

  • GET https://chastify.net/api/apps/v1/session
  • GET https://chastify.net/api/apps/v1/state
  • PUT https://chastify.net/api/apps/v1/state
  • PATCH https://chastify.net/api/apps/v1/state
  • GET https://chastify.net/api/apps/v1/metadata
  • PATCH https://chastify.net/api/apps/v1/metadata
  • POST https://chastify.net/api/apps/v1/action
  • POST https://chastify.net/api/apps/v1/lock/apply-time
  • POST https://chastify.net/api/apps/v1/lock/freeze
  • POST https://chastify.net/api/apps/v1/lock/unfreeze
  • POST https://chastify.net/api/apps/v1/logs/custom

Команды моста Iframe​

Полезные нагрузки команд моста отправляются через iframe (chastify:ext:req) и маршрутизируются родительским элементом Chastify. Мост намеренно ограничен операциями пользовательского интерфейса в безопасном режиме/сессии.

  • session.get -> GET https://chastify.net/api/extensions/sessions/:sessionId
  • state.get -> GET https://chastify.net/api/extensions/sessions/:sessionId/state
  • files.capabilities -> GET https://chastify.net/api/extensions/sessions/:sessionId/files/capabilities
  • files.list -> GET https://chastify.net/api/extensions/sessions/:sessionId/files
  • files.get -> GET https://chastify.net/api/extensions/sessions/:sessionId/files/:fileId с { "fileId": "file_record_id" }
  • metadata.get -> GET https://chastify.net/api/extensions/sessions/:sessionId/metadata
  • regularActions.get -> GET https://chastify.net/api/extensions/sessions/:sessionId/regular-actions

Конечные точки изменения сессии представляют собой прямые вызовы API бэкэнда, а не команды моста iframe. Это включает в себя запись состояния, обычную отправку действий и загрузку/удаление файлов во время выполнения, поскольку код iframe может контролироваться пользователем.

Примеры использования API сессий на стороне бэкэнда​

Для привилегированных вызовов, связанных с установленными расширениями, ваш бэкэнд должен отправлять оба заголовка:

Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEY
x-chastify-main-token: MAIN_TOKEN_FROM_IFRAME_HASH

Примеры действий на стороне бэкэнда:

  • metadata.patch -> PATCH /api/extensions/sessions/:sessionId/metadata
  • regularActions.submit -> POST /api/extensions/sessions/:sessionId/regular-actions
  • files.upload -> POST /api/extensions/sessions/:sessionId/files
  • files.delete -> DELETE /api/extensions/sessions/:sessionId/files/:fileId
  • lock.applyTime -> POST /api/extensions/sessions/:sessionId/action с { "name": "add_time", "params": <deltaSeconds> }
  • lock.freeze -> POST /api/extensions/sessions/:sessionId/action с { "name": "freeze", "params": { "durationSeconds": 900 } }
  • lock.unfreeze -> POST /api/extensions/sessions/:sessionId/action с { "name": "unfreeze", "params": {} }
  • lock.settings.patch -> POST /api/extensions/sessions/:sessionId/action с { "name": "settings.patch", "params": { ... } }
  • task.assign -> POST /api/extensions/sessions/:sessionId/action
  • task.start_timer -> POST /api/extensions/sessions/:sessionId/action с { "name": "task.start_timer", "params": {} }
  • task.complete -> POST /api/extensions/sessions/:sessionId/action с { "name": "task.complete", "params": { "successful": true } }
  • hygienic_unlock.start -> POST /api/extensions/sessions/:sessionId/action с { "name": "hygienic_unlock.start", "params": { "durationSeconds": 900 } }
  • pillory.end -> POST /api/extensions/sessions/:sessionId/action с { "name": "pillory.end", "params": {} }
  • device.command -> POST /api/extensions/sessions/:sessionId/device-command
  • logs.custom -> POST /api/extensions/sessions/:sessionId/logs/custom
  • notifications.custom -> POST /api/extensions/sessions/:sessionId/notifications/custom
  • requirements.progress -> POST /api/extensions/sessions/:sessionId/requirements/progress

Токен, область действия, аннулирование и поведение при аудите​

Используйте правильный токен для правильной границы доверия.

warning

Ключи API для разработчиков — это секреты. Если такой ключ окажется доступен в коде браузера, немедленно отзовите его и измените переменную среды бэкэнда.

Токен запуска Iframe (mainToken)​

  • Отображается в хеше iframe, когда пользователь открывает страницу установленного расширения.
  • Видимость в браузере предусмотрена изначально. Она идентифицирует открытую сессию расширения, но не является секретом бэкэнда.
  • Кратковременное действие. Текущие токены запуска истекают через 10 часов; для обновления обновите их, снова открыв страницу расширения.
  • Требуется значение x-chastify-main-token, когда ваш бэкэнд вызывает маршруты сессии установленного расширения, чтобы Chastify мог привязать запрос к бэкэнду к пользователю/сессии, открывшей расширение.
  • Не может использоваться отдельно для авторизации изменения времени, разблокировки завершения блокировки, завершения задач, команд устройства, загрузки/удаления данных во время выполнения, пользовательских журналов или пользовательских уведомлений.

Ключ API для разработчиков, ограниченный областью действия приложения.​

  • Создано на основе пользовательского интерфейса разработчика для одного приложения-расширения.
  • Секрет, доступный только на бэкэнде. Никогда не размещайте его в JavaScript-коде iframe, пакетах мобильных приложений, конфигурации статического хостинга или логах, читаемых браузером.
  • Используется с Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEY и x-chastify-main-token.
  • Вызов API для сеансов установленных расширений возможен только для сеансов, соответствующих приложению расширения и токену запуска.
  • Срок действия не истекает автоматически. Отзовите его немедленно, если он станет доступен, и регулярно обновляйте переменную среды бэкэнда.

Ключ API для разработчиков, доступный пользователю в масштабе всей системы.​

  • Создано через пользовательский интерфейс разработчика без выбора приложения-расширения.
  • Секретный ключ, доступный только на стороне бэкэнда, для /api/apps/v1/*.
  • Управляет текущими и будущими активными сеансами блокировки, принадлежащими владельцу ключа.
  • Не может использоваться в качестве учетных данных для бэкэнда установленного стороннего расширения.

Отмена​

  • Отозванные API-ключи для разработчиков прекращают авторизацию новых запросов.
  • Отозванные ключи можно безвозвратно удалить из пользовательского интерфейса разработчика.
  • При запуске новых iframe-элементов используются новые токены запуска. Не следует хранить mainToken в качестве долговременных учетных данных.

Сферы деятельности и роли​

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

Аудит и лимиты​

  • Метаданные о последнем использовании ключа API разработчика обновляются при каждом использовании ключа.
  • Маршруты привилегированных действий имеют ограничение по скорости и возвращают явные ошибки, такие как server_credentials_required или user_wide_dev_key_required, при использовании неправильного типа учетных данных.
  • Пользовательские журналы записывают видимые записи истории блокировок.
  • Пользовательские уведомления создают уведомления Chastify для запрошенного целевого объекта.
  • Полное аудиторское покрытие для каждого изменения привилегированного расширения отслеживается как элемент повышения безопасности в производственной среде.

Поддерживаемые значения команд​

/api/extensions/sessions/:sessionId/action и /api/apps/v1/action​

name поддерживает:

  • add_time
  • remove_time
  • freeze
  • pillory
  • unfreeze
  • toggle_freeze
  • settings.patch
  • task.assign
  • task.start_timer
  • task.complete
  • hygienic_unlock.start
  • pillory.end

Ограничения действий:

  • Для выполнения задач необходимо включить расширение/модуль «Задачи» на замке.
  • Для работы hygienic_unlock.start требуется включить функцию «Гигиеническое открытие» и не запускать активную гигиеническую сессию.

session.get вспомогательные данные блокировки​

session.get / GET /api/apps/v1/session также включает lockData с удобными для выполнения логическими значениями, числами и строками для механизмов правил.

Примеры:

  • логические значения: frozen, unlockable, trusted, taskAssigned (true, если существует открытый TaskRun)
  • номера: timeLockedSeconds, timeRemainingSeconds, maxTimeRemainingSeconds, taskPoints
  • строка: lockTitle, поля профиля пользователя/владельца ключа

Конфиденциальность:

  • wearerLastSeenTimestamp и keyholderLastSeenTimestamp становятся null, когда пользователь отключил онлайн-статус (showOnlineStatus === false).

Команды устройства​

В сеансах расширения можно использовать конечную точку на основе сеанса:

POST /api/extensions/sessions/:sessionId/device-command

Внешние программы, использующие токен DEV, могут применять более простую конечную точку версии 1 (идентификатор сессии не требуется):

POST /api/apps/v1/device-command

Оба запроса принимают одно и то же тело запроса и возвращают один и тот же ответ. Подробную информацию см. в разделе Внешний API и программы.

Страница настроек (необязательно, рекомендуется)​

Если ваше расширение имеет пользовательский интерфейс настройки/конфигурации:

  1. Родительский компонент отправляет chastify:ext:setup:init (сохраненная конфигурация + контекст).
  2. В вашем iframe-элементе настройки отображаются обновления с кодом chastify:ext:setup:config.
  3. Родитель может запросить текущую конфигурацию, используя код chastify:ext:setup:get_config.

Процесс обработки токенов на стороне бэкэнда (когда необходимы вызовы на стороне сервера)​

Для простых скриптов и внешних программ используйте токен DEV, доступный на странице API для разработчиков. См. Внешний API и программы.

Стандартный сценарий работы расширения в режиме iframe:

  1. Chastify выдает кратковременный видимый в браузере токен запуска для активной сессии расширения.
  2. Токен запуска внедряется в хэш-нагрузку iframe под номером mainToken.
  3. Ваш iframe перенаправляет mainToken на ваш бэкэнд.
  4. Ваш бэкэнд вызывает https://chastify.net/api/extensions/sessions/:sessionId/* с параметрами Authorization: Bearer <app-scoped Developer API key> и x-chastify-main-token: <mainToken>.

Не отправляйте ключи API разработчика в код iframe/браузера. mainToken идентифицирует открытую сессию расширения; это не секретный ключ бэкэнда, и сам по себе он не может использоваться для привилегированных действий.

Ручной резервный вариант:

  • Если вам необходимо получить/повернуть токен запуска iframe непосредственно из пользовательского интерфейса, вызовите GET https://chastify.net/api/extensions/sessions/:sessionId/auth.

Используйте режим бэкэнда, если вам нужны запланированные задания, веб-хуки или автоматизация, когда страница Chastify не открыта. Текущие изменения сессии установленных расширений по-прежнему требуют действительного 10-часового токена запуска iframe, поэтому в автоматических заданиях следует сохранять ожидающее подтверждение и отправлять его при следующем действительном запуске, если вы не используете собственный/встроенный серверный поток, предназначенный для фонового выполнения.

к сведению

Для полностью автоматизированного функционирования в производственной среде предпочтительнее использовать встроенный/собственный серверный поток или дождаться явного предоставления фоновых расширений. API сессий, ограниченные областью действия приложения, в настоящее время привязаны к токену запуска.

Backend против Cloudflare Pages (без сервера)​

Используйте Cloudflare Pages (без серверной части), когда:​

  • Вам нужна самая простая и дешевая настройка (с возможностью бесплатного размещения).
  • Действия, управляемые пользовательским интерфейсом, необходимы только тогда, когда пользователь активно находится на странице вашего расширения.
  • Вам не требуется запись состояния расширения, сохраняемого на сервере.
  • Вы занимаетесь прототипированием или быстрой разработкой легковесных расширений.

Пример локального тестирования (PowerShell):

cloudflared tunnel --url http://localhost:5174

Используйте сгенерированный общедоступный URL-адрес в качестве URL-адреса вашего iframe во время тестирования.

Используйте серверную часть, когда:​

  • Вам необходимы запланированные задания (работающие по принципу cron).
  • Вам потребуются веб-хуки или внешние интеграции.
  • Вам потребуется автоматизация/фоновая обработка, когда на странице расширения никого нет.
  • Вам необходимы управляемые сервером рабочие процессы, которые должны выполняться непрерывно.

Важное ограничение при отсутствии бэкэнда:

  • Фоновое выполнение не требуется. Ваше расширение может выполнять действия только в том случае, если пользователь в данный момент открыл iframe расширения и взаимодействует с ним.

Общие проблемы​

  • 403 extension_not_enabled: расширение не включено для этого замка.
  • 409 lock_ended: блокировка больше не активна.
  • 429: достигнут лимит запросов.
  • Нет ответов в iframe: проверьте nonce, targetOrigin (parentOrigin) и разрешенные источники.

Следующие руководства​