Angelic-Angel README

The project's README from github.com/sh1ma/Angelic-Angel. As one markdown file: README.md.

Angelic Angel

"Angelic Angel/Hello, Hoshi wo Kazoete" is a single by μ's released on July 1, 2015 from Lantis. The song is an insert song for the film Love Live! The School Idol Movie.

— Wikipedia

A CLI tool that receives Twitter/X notifications in real time via Mozilla's Web Push infrastructure. Stream tweets from users you follow and have tweet notifications enabled for.

日本語版 README

Overview

Angelic Angel emulates a browser's Web Push client to receive Twitter/X push notifications. It connects to Mozilla AutoPush via WebSocket, decrypts incoming notifications using ECE (Encrypted Content-Encoding), and forwards the decrypted payloads to a configured webhook endpoint.

You will receive notifications for tweets from users that you follow and have tweet notifications turned on for on Twitter/X.

How It Works

Twitter/X  ──push──▶  Mozilla AutoPush Server  ◀──WebSocket──  Angelic Angel  ──HTTP POST──▶  Webhook
  1. Angelic Angel registers as a Web Push subscriber with Mozilla's AutoPush server.
  2. The push subscription endpoint is registered with Twitter's notification settings API.
  3. When Twitter sends a push notification, it goes through Mozilla's AutoPush server — the same infrastructure used by Firefox.
  4. Angelic Angel receives and decrypts the notification via WebSocket, then forwards the payload to your webhook.

Important Notes

Requirements

Getting auth_token and ct0

  1. Open x.com in your web browser and log in.
  2. Open Developer Tools (F12) and go to the Application (or Storage) tab.
  3. Under Cookies → https://x.com, find the values for auth_token and ct0.

Installation

cargo install --path .

Usage

1. Initialize configuration

# Interactive mode
angelic-angel init

# Or with arguments
angelic-angel init --auth-token YOUR_AUTH_TOKEN --ct0 YOUR_CT0

This creates angelic-angel.toml with your Twitter credentials.

2. Register push subscription

angelic-angel register

This registers a new push subscription with Mozilla AutoPush and then registers the endpoint with Twitter's push notification API.

3. Start listening

WEBHOOK_ENDPOINT=https://your-webhook.example.com/endpoint angelic-angel listen

The WEBHOOK_ENDPOINT environment variable specifies where decrypted notification payloads are sent via HTTP POST.

Other commands

# Check current configuration and registration status
angelic-angel status

# Remove push subscription
angelic-angel unregister

Options

Flag Description
-c, --config <PATH> Configuration file path (default: angelic-angel.toml)
-v, --verbose Enable debug logging

Reconnection

Angelic Angel implements a Firefox-compatible reconnection strategy:

License

MIT

Angelic-Angel (sh1ma/Angelic-Angel)

Searching Database…

839 ·GitHub
Angelic-Angel
Что это?Angelic Angel — консольный инструмент на Rust, который получает push-уведомления Twitter/X в реальном времени, эмулируя Web Push-клиент браузера, подключаясь к инфраструктуре Mozilla AutoPush и пересылая расшифрованные полезные нагрузки уведомлений на ваш webhook.
Это скрейпинг моей ленты Twitter или что-то другое?Никакого скрейпинга. Используется стандартный сценарий W3C Push API — тот же механизм, что и в браузере: через WebSocket подключается к серверу Mozilla AutoPush и обращается к API Twitter лишь один раз, чтобы зарегистрировать push-подписку.
Как его запустить?Сначала выполните команду init, чтобы создать файл конфигурации angelic-angel.toml с вашими учётными данными Twitter, затем выполните register, чтобы создать push-подписку с Mozilla AutoPush и привязать её к API уведомлений Twitter, и наконец выполните команду listen с переменной окружения WEBHOOK_ENDPOINT, чтобы расшифрованные полезные нагрузки отправлялись POST-запросами в выбранное вами место.
Что нужно, прежде чем им пользоваться?Нужен Rust (edition 2024) для сборки, а также ваши authtoken и cookie ct0 от Twitter/X, которые берутся на вкладке Application/Storage инструментов разработчика браузера после входа на x.com.
Поймает ли это твиты любого нужного мне аккаунта?Нет — уведомления приходят только по аккаунтам, на которые вы подписаны и для которых специально включили уведомления о твитах на Twitter/X, — так же, как вели бы себя настоящие push-уведомления.
Откуда на самом деле приходят данные уведомлений?Все данные уведомлений поступают с Web Push-сервера Mozilla (push.services.mozilla.com), а не напрямую от Twitter; к API Twitter обращение происходит лишь один раз — при первоначальной регистрации подписки.
Как он обрабатывает разрывы WebSocket-соединений?Используется совместимая с Firefox стратегия переподключения: экспоненциальная задержка с 5 секунд с удвоением до предела в 5 минут, автоматическая перерегистрация, если UAID стал недействительным, и ожидание 30 минут, если сервер прислал код закрытия с отсрочкой (4774).
Что именно происходит при поступлении уведомления о твите?Angelic Angel расшифровывает входящую push-полезную нагрузку с помощью ECE (Encrypted Content-Encoding) и отправляет расшифрованные данные на настроенный вами webhook методом HTTP POST.
Почему он называется «Angelic Angel»?Это шутливая отсылка к «Angelic Angel/Hello, Hoshi wo Kazoete» — синглу 2015 года группы μ's из фильма Love Live!, не связанная с реальной функцией инструмента.
What are similar projects?tincan-cli, webhook, pdfcraft, chisel, curl, ngrok, apprise, smartdns
Which topics is it in?mozilla, webhook, twitter, firefox, webhooks, notifications, websocket, http, real-time, encryption, utility, networking
Creator
sh1ma
Size
<0.1 MB
Stars
839
Updated
CommitMar 05
Age
7mo
Commits · 90 Days