IMSEL Crypto API¶
API crypto.imsel.dev преобразует адрес подписки в
шифрованную ссылку imsel://crypt/.... Он предназначен для серверной интеграции
провайдера: Telegram-бота, кабинета или панели управления подписками.
Сервис не загружает содержимое переданного адреса и не проверяет доступность подписки. Для открытия результата требуется обновлённый IMSEL VPN с поддержкой этого формата. В обновлённой версии новая crypt-подписка с непустым именем во фрагменте источника добавляется без отдельного подтверждения; без такого имени приложение предлагает подтверждение без раскрытия адреса. VPN от самого добавления автоматически не подключается.
Доступ и безопасность¶
Базовый адрес: https://crypto.imsel.dev.
Используйте точные маршруты ниже без завершающего / и query-параметров.
Для интеграции нужен токен доступа, выданный администрацией сервиса. Автоматической регистрации и самостоятельной выдачи персональных API-ключей сейчас нет. Условия доступа и применимую общую квоту согласуйте до интеграции.
Каждый запрос к /v1/encrypt, /v1/personal/encrypt и /v1/usage содержит:
Храните токен только на своей серверной стороне. Не размещайте его в приложении, публичном коде бота, JavaScript страницы, URL, сообщениях Telegram или журналах. Не передавайте токен клиентам провайдера. При утечке обратитесь к администрации для замены; публичного endpoint отзыва токена сейчас нет.
API-токен разрешает вызов сервиса. Он не является ключом шифрования ссылки, идентификатором телефона или подтверждением права пользователя на VPN-подписку.
Используйте HTTPS с обычной проверкой сертификата. Запросы не должны следовать
перенаправлениям на другой адрес: токен и исходная подписка не должны уходить
постороннему получателю. Для интеграции используйте только публичные /v1/-методы
ниже, а не endpoint формы сайта. Серверным API-вызовам проверка Turnstile не нужна;
это не разрешение отключать её на публичном сайте.
Создание обычной ссылки¶
POST /v1/encrypt¶
POST /v1/encrypt HTTP/1.1
Host: crypto.imsel.dev
Authorization: Bearer <API_TOKEN>
Content-Type: application/json
| Поле | Обязательное | Правило |
|---|---|---|
url |
Да | Строка источника подписки, до 16 384 байт UTF-8 |
provider_name |
Нет | Отображаемое имя провайдера, до 128 байт UTF-8, без управляющих символов |
provider_name не создаёт аккаунт, не назначает права и не выбирает отдельную
квоту. Эта подпись видна в готовой ссылке; не помещайте в неё секреты.
Она также не заменяет имя во фрагменте источника для автоматического добавления
в обновлённом приложении.
Передавайте JSON в UTF-8. Допустим Content-Type: application/json либо
application/json; charset=utf-8. Сжатые тела запроса не принимаются. Размер
всего тела — не более 100 000 байт. null, вложенные объекты вместо строк,
неизвестные поля и повторения полей отклоняются.
Этот маршрут создаёт только обычный формат crypt. Поля hwid и public_key
здесь отклоняются, а не игнорируются. Для персональной ссылки используйте
отдельный маршрут ниже.
Поддерживаемый источник¶
Поле url может содержать:
- HTTP- или HTTPS-адрес, допустимый публичный IP и порт.
- Query-параметры и фрагмент
#с именем подписки. - Параметры домен-фронтинга.
- Зеркала, разделённые
|или переводами строк, включаяurl:0=,url:1=иfallback-url=.
Пример с вымышленными зеркалами:
{
"url": "url:0=https://example.com/primary#Example|url:1=https://example.org/backup|fallback-url=https://example.net/fallback",
"provider_name": "Example VPN"
}
Передавайте исходную строку точно: не удаляйте фрагмент, не переставляйте зеркала
и не кодируйте весь адрес в percent-encoding перед помещением в JSON. JSON-экранирование
переводов строк и кавычек необходимо; это не дополнительное кодирование самого URL.
Существующие %-последовательности адреса должны сохраниться.
Ограничения безопасности сохраняются: отклоняются запрещённые локальные/приватные IP-адреса и служебные имена, логин и пароль внутри URL, некорректное кодирование, обратные косые черты и недопустимые управляющие символы. Один некорректный сегмент отклоняет весь источник. DNS-разрешение не проверяется: допустимый hostname не гарантирует публичность его фактического адреса или успешную загрузку. По возможности используйте HTTPS: crypt-ссылка не защищает последующую загрузку по HTTP.
API принимает именно источник HTTP(S), а не готовые imsel://add,
imsel://import или imsel://crypt ссылки. Если интеграция получает обычную
add/import-обёртку, сначала проверьте её и извлеките единственное значение url
одним query-декодированием. Не выполняйте повторное декодирование, не принимайте
config, неизвестные/повторные внешние параметры и рекурсивные обёртки.
Ответ¶
Успех — HTTP 200, Content-Type: application/json, Cache-Control: no-store:
<payload> здесь — обозначение результата, не рабочая ссылка. В реальном ответе
на его месте находятся готовые шифрованные данные. Не изменяйте их, не добавляйте
к ним параметры и не перекодируйте содержимое вручную.
Исходный адрес в ответе не возвращается. API не выдаёт отдельное поле имени,
не возвращает серверы подписки и не принимает желаемый тип add/import в запросе.
Нужную внешнюю форму интеграция создаёт сама, как описано ниже.
Предельная длина encrypted_url — 186 681 символ. Не все приложения и каналы
передачи допускают столь длинную ссылку. В частности, обычное текстовое сообщение
Telegram ограничено 4096 символами после обработки форматирования: проверяйте
длину до отправки, не обрезайте payload и не делите crypt-ссылку на отдельные ссылки.
Ограничения выбранного способа доставки проверяйте отдельно; максимальный размер
ответа API не является гарантией его пересылки одним сообщением бота.
Пример cURL¶
В примере IMSEL_CRYPTO_API_TOKEN — переменная окружения вашего серверного
процесса с выданным токеном. Команда приведена для POSIX-совместимой оболочки;
не вставляйте рабочий токен прямо в команду, которую сохраняете или публикуете.
curl --silent --show-error --fail-with-body \
--connect-timeout 5 --max-time 15 \
'https://crypto.imsel.dev/v1/encrypt' \
--header "Authorization: Bearer ${IMSEL_CRYPTO_API_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{"url":"https://example.com/subscription#Example","provider_name":"Example VPN"}'
Не добавляйте --location или отключение проверки TLS. Вывод успешного запроса
содержит crypt-ссылку на вашу подписку: не сохраняйте его в общий журнал, историю
CI или публичный отчёт. Не используйте отладочный вывод HTTP-заголовков с токеном.
Даже токен из переменной окружения может попасть в аргументы запущенной команды;
в рабочей интеграции передавайте его средствами защищённого серверного окружения.
Создание персональной ссылки¶
POST /v1/personal/encrypt¶
Маршрут опубликован на https://crypto.imsel.dev. Для вызова требуется
согласованный API-доступ. Открытие результата требует обновлённого IMSEL VPN
с поддержкой personal-v1.
Маршрут использует тот же API-токен вызывающей интеграции, что и обычный
/v1/encrypt. Новый секрет для шифрования со стороны клиента не нужен:
передаются HWID и/или публичный ключ, а не закрытый ключ.
POST /v1/personal/encrypt HTTP/1.1
Host: crypto.imsel.dev
Authorization: Bearer <API_TOKEN>
Content-Type: application/json
| Поле | Обязательное | Правило |
|---|---|---|
url |
Да | Тот же поддерживаемый источник, до 16 384 байт UTF-8 |
provider_name |
Нет | Отображаемая подпись, до 128 байт UTF-8, без управляющих символов |
hwid |
Хотя бы одно из hwid / public_key |
Непустой HWID получателя, до 256 байт UTF-8 |
public_key |
Хотя бы одно из hwid / public_key |
Публичный ключ RSA-2048 из приложения: SPKI DER в каноническом Base64url без =, пробелов и PEM-обёртки; не более 1366 символов |
Общие правила JSON, размера тела и допустимости источника из раздела обычного
шифрования действуют и здесь. Не передавайте пустое значение вместо отсутствующего
поля, null, закрытый ключ или произвольный текст вместо публичного ключа.
Публичный ключ нужно скопировать из обновлённого приложения получателя, а не
генерировать вместо него новый ключ на стороне провайдера.
Режимы получателя¶
| Переданные поля | Условие открытия |
|---|---|
Только hwid |
Совпадение HWID |
Только public_key |
Наличие соответствующего закрытого ключа у приложения получателя; HWID не требуется |
| Оба поля | Одновременно соответствующий ключ приложения И совпадающий HWID |
В режиме с обоими полями одно совпадение не заменяет второе. При несовпадении
условий нет перехода к более слабому режиму или к общему ключу обычного crypt.
HWID может быть известен или подменён: привязка только к нему слабее привязки
к ключу приложения. Ссылку с привязкой к ключу нельзя открыть одним общим
AES-ключом обычного формата.
Получите HWID и публичный ключ у клиента из раздела идентификации устройства в настройках обновлённого приложения. Используйте значения именно предполагаемого получателя. Закрытый ключ не вводится в форму, не передаётся в API и не хранится этим сервисом. После потери ключа, например при переустановке, ссылку с привязкой к ключу необходимо выпустить заново для актуального публичного ключа.
Проверка условий и расшифровка выполняются локально, в том числе без сети. Загрузка подписки с полученного URL требует сети. Здесь нет входа в аккаунт, Provider ID, регистрации устройства, счётчика установок или сетевой активации; API не проверяет, владеет ли отправитель указанным устройством.
Примеры запроса и ответа¶
Вымышленный пример только с HWID; DEMO-HWID-0001 не является идентификатором
реального устройства:
curl --silent --show-error --fail-with-body \
--connect-timeout 5 --max-time 15 \
'https://crypto.imsel.dev/v1/personal/encrypt' \
--header "Authorization: Bearer ${IMSEL_CRYPTO_API_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{"url":"https://example.com/subscription#Example","provider_name":"Example VPN","hwid":"DEMO-HWID-0001"}'
Для режима только с ключом форма JSON выглядит так:
PUBLIC_KEY_FROM_CLIENT является заведомо недействительным обозначением,
не публичным ключом. Такой запрос без замены значения будет отклонён.
Для режима с обоими условиями добавьте hwid того же получателя; не убирайте
ошибочное поле ради получения ссылки с ослабленной привязкой.
Успех: HTTP 200, JSON с Cache-Control: no-store:
Сохраните payload без изменений. Внешние формы add/import строятся так же,
как для обычного результата; проверяйте именно format: "personal-v1".
Правила хранения токена, TLS, таймаутов и непубликации результата из обычного
примера cURL остаются обязательными.
Crypt, add и import¶
Из одного результата encrypted_url можно получить три формы:
| Назначение | Результат |
|---|---|
| Самостоятельная crypt-ссылка | Вернуть encrypted_url без изменений |
| Шифрованное добавление | imsel://add?url=crypt/<payload> |
| Шифрованный импорт | imsel://import?url=crypt/<payload> |
Для короткой формы проверьте точный префикс imsel://crypt/ и возьмите его
неизменённое продолжение <payload>. Не расшифровывайте его. Добавьте только
внешнюю обёртку imsel://add?url=crypt/ или imsel://import?url=crypt/.
Внешний параметр name не поддерживается.
Другой допустимый вариант — целиком поместить encrypted_url в percent-encoding
как значение внешнего url. Не кодируйте это значение второй раз.
Самостоятельная crypt-ссылка и encrypted add/import требуют совместимой версии
приложения. Для автоматического добавления новой подписки по непустому имени
после # и до параметров после ? требуется обновлённая версия приложения.
Без такого имени остаётся подтверждение без раскрытия адреса; одна подпись
provider_name не разрешает автоматическое добавление. Выбирается первое непустое
имя по порядку обычных зеркал после URL-декодирования и удаления пробелов по краям,
без fallback-url. Фрагмент только с параметрами после #? не считается именем.
Загрузка подписки ради поиска имени
в HTTP-ответе до решения о добавлении не выполняется. После сохранения начинается
обычная загрузка без автоматического подключения VPN.
В обновлённой версии адрес новой crypt-подписки защищён от отображения,
копирования, редактирования и раздачи в режиме URL. Права на конфигурации
серверов остаются независимыми. Ранее добавленные записи, в том числе при
повторном импорте совпадающей crypt-ссылки, не получают эту защиту задним числом.
Обычные add/import без шифрования сохраняют прежнее поведение,
не требуют вызова этого API и не скрывают исходный адрес.
Подробности: форматы добавления и подтверждение.
Учёт использования¶
GET /v1/usage¶
Использует тот же Authorization: Bearer …. Тело и query-параметры не нужны:
curl --silent --show-error --fail-with-body \
--connect-timeout 5 --max-time 15 \
'https://crypto.imsel.dev/v1/usage' \
--header "Authorization: Bearer ${IMSEL_CRYPTO_API_TOKEN}"
Пример ответа; счётчики приведены условно:
| Поле | Значение |
|---|---|
total |
Накопленный расход общего лимита |
minute |
Расход текущей фиксированной минуты |
day |
Расход текущего дня UTC |
limits |
Действующие пределы, а не остатки |
Персональный режим не добавляет отдельных полей или счётчиков в этот ответ.
Сейчас лимиты общие для сайта и серверного API, включая персональную форму
и /v1/personal/encrypt, а не отдельные для каждого
провайдера или токена: 10 в минуту, 1000 в день UTC, 100 000 суммарно. Значения
могут меняться администрацией; интеграция должна читать действующие limits,
а не считать эти числа неизменной персональной квотой.
Операция резервируется в общей квоте до шифрования. Сбой после допуска, отмена или потеря ответа
могут потратить одну операцию без получения результата. total не равен числу
успешных импортов; открытие ссылки в телефоне не увеличивает эти счётчики.
Есть дополнительные ограничения частоты попыток. Даже при свободной квоте
шифрования возможен 429; /v1/usage не обещает показать все такие ограничения.
Ошибки и повторы¶
Пример тела ошибки:
| HTTP | error |
Действие интеграции |
|---|---|---|
400 |
invalid_request |
Проверить JSON, поля и типы значений |
400 |
invalid_url |
Исправить весь источник, включая зеркала/fronting |
400 |
invalid_provider |
Проверить имя, UTF-8-размер и управляющие символы |
400 |
invalid_hwid |
Проверить непустой HWID и предел 256 байт UTF-8 |
400 |
invalid_public_key |
Передать публичный ключ приложения RSA-2048 в каноническом Base64url SPKI DER |
400 |
recipient_required |
Для персонального маршрута передать хотя бы hwid или public_key |
400 |
https_required |
Обращаться к API по HTTPS |
401 |
unauthorized |
Проверить доступ; не повторять бесконечно тем же токеном |
404 |
not_found |
Проверить точный host и route; query у методов API не используется |
405 |
method_not_allowed |
Использовать POST для выбранного маршрута шифрования или GET usage; проверить Allow |
408 |
request_timeout |
Тело не поступило вовремя; проверить отправку и сеть |
413 |
too_large |
Уменьшить тело или источник |
415 |
unsupported_media_type |
Передать JSON UTF-8 без Content-Encoding |
429 |
rate_limited |
Соблюдать Retry-After; выяснить, не исчерпан ли дневной/суммарный лимит |
503 |
unavailable |
Временная недоступность; ограниченные повторы с задержкой |
На 401 возвращается WWW-Authenticate: Bearer. На 429 — Retry-After: 60.
Этот интервал не гарантирует восстановление дневной или суммарной квоты:
суммарный предел сам не сбрасывается. Не превращайте повтор через минуту в
бесконечный цикл. Не рассчитывайте на индивидуальные X-RateLimit-* или
X-Request-ID: сейчас они не являются контрактом этого API.
Идемпотентность повторов не реализована. Заголовок Idempotency-Key не гарантирует
ни возврат прежней ссылки, ни однократный расход квоты. Повтор одного URL может
создать другой шифрованный результат и потратить ещё одну операцию. После таймаута
клиента исход операции может быть неизвестен; не запускайте параллельные повторы.
Подключение Telegram-бота или панели¶
Рекомендуемая последовательность интеграции:
- Получить согласованный доступ у администрации и сохранить токен на своей серверной стороне, отдельно от исходников и URL.
- Получить источник подписки от своей панели. Не загружать его содержимое ради вызова encrypt: API требуется только адрес.
- Выбрать
POST /v1/encryptдля обычного результата либоPOST /v1/personal/encryptдля персонального. Во втором случае получить нужные публичные данные получателя. Задать конечный таймаут, проверять TLS и не следовать перенаправлениям с credential. - При
200проверить JSON, ожидаемыйformat(cryptилиpersonal-v1) и префиксencrypted_url. Отправить клиенту только готовую ссылку или построенную encryptedadd/importобёртку. Это преобразование выполняется после API, не новым полем запроса. - При ошибке показать безопасное сообщение. Не публиковать токен, исходный URL, тело запроса или подробное исключение. Повторы ограничить по правилам выше.
Токен доступа к API не передаётся в отправляемую клиенту ссылку. Если исходный адрес присылают сообщением самому боту, он уже передан Telegram; вызов encrypt не отменяет этого. Персональные источники предпочтительно получать из своей панели, а не просить клиента отправлять их в общий чат.
Этот API можно использовать из панели, которую вы разрабатываете. Персональный маршрут проверяет допустимость переданных HWID и публичного ключа, но не подтверждает личность получателя, владение устройством или подпись запроса загрузки подписки. Он не предоставляет endpoint регистрации устройства, отзыва VPN-доступа, биллинга, удаления опубликованных crypt-ссылок или назначения прав ISPS. Эти функции не следуют из токена encrypt и не должны обозначаться как уже доступные.
Ограничения защиты¶
Обычная ссылка crypt маскирует исходный адрес с помощью общего ключа приложения.
Это не абсолютная секретность от получателя, изменённого приложения или целевого
исследования клиента. Crypt не заменяет HTTPS, персональные токены подписок и
отзыв доступа на стороне провайдера. Имя провайдера — подпись для отображения,
а не подтверждение его личности. Не публикуйте личные crypt-ссылки в примерах.
Персональный режим добавляет выбранные условия открытия, но не предоставляет отзыв уже выданной ссылки через Crypto API и не отзывает исходную подписку. Доступ к исходной подписке отзывается на стороне её провайдера. Защита адреса в интерфейсе обновлённого приложения также не является абсолютной защитой от изменённого клиента или устройства с root и не меняет старые записи задним числом.
Для ручной работы доступен генератор IMSEL Crypto. Он использует отдельную проверку формы; его публичная доступность не выдаёт право на серверный API и не раскрывает API-токен. Персональные режимы формы доступны на сайте и требуют проверки Turnstile. Отсутствие Turnstile у серверного API не разрешает обход проверки браузерной формы.