Перейти к содержанию

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 содержит:

Authorization: Bearer <API_TOKEN>

Храните токен только на своей серверной стороне. Не размещайте его в приложении, публичном коде бота, 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": "https://example.com/subscription?plan=demo#Example",
  "provider_name": "Example VPN"
}
Поле Обязательное Правило
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:

{
  "encrypted_url": "imsel://crypt/<payload>",
  "format": "crypt"
}

<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 выглядит так:

{
  "url": "https://example.com/subscription#Example",
  "public_key": "PUBLIC_KEY_FROM_CLIENT"
}

PUBLIC_KEY_FROM_CLIENT является заведомо недействительным обозначением, не публичным ключом. Такой запрос без замены значения будет отклонён. Для режима с обоими условиями добавьте hwid того же получателя; не убирайте ошибочное поле ради получения ссылки с ослабленной привязкой.

Успех: HTTP 200, JSON с Cache-Control: no-store:

{
  "encrypted_url": "imsel://crypt/<payload>",
  "format": "personal-v1"
}

Сохраните 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": 17,
  "minute": 0,
  "day": 4,
  "limits": {
    "minute": 10,
    "day": 1000,
    "lifetime": 100000
  }
}
Поле Значение
total Накопленный расход общего лимита
minute Расход текущей фиксированной минуты
day Расход текущего дня UTC
limits Действующие пределы, а не остатки

Персональный режим не добавляет отдельных полей или счётчиков в этот ответ.

Сейчас лимиты общие для сайта и серверного API, включая персональную форму и /v1/personal/encrypt, а не отдельные для каждого провайдера или токена: 10 в минуту, 1000 в день UTC, 100 000 суммарно. Значения могут меняться администрацией; интеграция должна читать действующие limits, а не считать эти числа неизменной персональной квотой.

Операция резервируется в общей квоте до шифрования. Сбой после допуска, отмена или потеря ответа могут потратить одну операцию без получения результата. total не равен числу успешных импортов; открытие ссылки в телефоне не увеличивает эти счётчики. Есть дополнительные ограничения частоты попыток. Даже при свободной квоте шифрования возможен 429; /v1/usage не обещает показать все такие ограничения.

Ошибки и повторы

Пример тела ошибки:

{"error":"invalid_url"}
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-бота или панели

Рекомендуемая последовательность интеграции:

  1. Получить согласованный доступ у администрации и сохранить токен на своей серверной стороне, отдельно от исходников и URL.
  2. Получить источник подписки от своей панели. Не загружать его содержимое ради вызова encrypt: API требуется только адрес.
  3. Выбрать POST /v1/encrypt для обычного результата либо POST /v1/personal/encrypt для персонального. Во втором случае получить нужные публичные данные получателя. Задать конечный таймаут, проверять TLS и не следовать перенаправлениям с credential.
  4. При 200 проверить JSON, ожидаемый format (crypt или personal-v1) и префикс encrypted_url. Отправить клиенту только готовую ссылку или построенную encrypted add/import обёртку. Это преобразование выполняется после API, не новым полем запроса.
  5. При ошибке показать безопасное сообщение. Не публиковать токен, исходный 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 не разрешает обход проверки браузерной формы.