fresta 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. fresta-0.2.0/LICENSE +34 -0
  2. fresta-0.2.0/PKG-INFO +225 -0
  3. fresta-0.2.0/README.md +188 -0
  4. fresta-0.2.0/fresta/__init__.py +26 -0
  5. fresta-0.2.0/fresta/py.typed +6 -0
  6. fresta-0.2.0/fresta.egg-info/PKG-INFO +225 -0
  7. fresta-0.2.0/fresta.egg-info/SOURCES.txt +38 -0
  8. fresta-0.2.0/fresta.egg-info/dependency_links.txt +1 -0
  9. fresta-0.2.0/fresta.egg-info/entry_points.txt +8 -0
  10. fresta-0.2.0/fresta.egg-info/requires.txt +9 -0
  11. fresta-0.2.0/fresta.egg-info/top_level.txt +2 -0
  12. fresta-0.2.0/pyproject.toml +147 -0
  13. fresta-0.2.0/schemas/client.schema.json +73 -0
  14. fresta-0.2.0/schemas/server.schema.json +107 -0
  15. fresta-0.2.0/scripts/__init__.py +0 -0
  16. fresta-0.2.0/scripts/check/__init__.py +0 -0
  17. fresta-0.2.0/scripts/check/sanity.py +149 -0
  18. fresta-0.2.0/scripts/deploy/__init__.py +0 -0
  19. fresta-0.2.0/scripts/deploy/bench.py +131 -0
  20. fresta-0.2.0/scripts/deploy/check_health.py +225 -0
  21. fresta-0.2.0/scripts/deploy/diff_configs.py +197 -0
  22. fresta-0.2.0/scripts/deploy/fresta_gen_vless.py +506 -0
  23. fresta-0.2.0/scripts/deploy/validate_config.py +226 -0
  24. fresta-0.2.0/scripts/harvest/__init__.py +0 -0
  25. fresta-0.2.0/scripts/harvest/harvest_subscription.py +178 -0
  26. fresta-0.2.0/scripts/harvest/harvest_twl.py +542 -0
  27. fresta-0.2.0/scripts/recon/__init__.py +0 -0
  28. fresta-0.2.0/scripts/recon/fresta_recon.py +294 -0
  29. fresta-0.2.0/scripts/relay/__init__.py +0 -0
  30. fresta-0.2.0/scripts/relay/fresta_client.py +145 -0
  31. fresta-0.2.0/scripts/relay/yc_function/__init__.py +0 -0
  32. fresta-0.2.0/scripts/relay/yc_function/handler.py +111 -0
  33. fresta-0.2.0/scripts/tests/__init__.py +0 -0
  34. fresta-0.2.0/scripts/tests/probe_reality.py +83 -0
  35. fresta-0.2.0/scripts/tests/test_gen_vless.py +105 -0
  36. fresta-0.2.0/scripts/tests/test_handler.py +143 -0
  37. fresta-0.2.0/scripts/tests/test_harvest.py +145 -0
  38. fresta-0.2.0/scripts/tests/test_harvest_twl.py +246 -0
  39. fresta-0.2.0/scripts/tests/test_recon.py +96 -0
  40. fresta-0.2.0/setup.cfg +4 -0
fresta-0.2.0/LICENSE ADDED
@@ -0,0 +1,34 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024-2026 fresta contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
23
+ ---
24
+
25
+ Дополнительное уведомление (юридическая рамка проекта, не меняет лицензию):
26
+
27
+ Программное обеспечение предоставляется «как есть» для исследования и личного
28
+ использования. Применение может нарушать ToS операторов связи, CDN и
29
+ облачных провайдеров; в ряде юрисдикций обход ограничений доступа может
30
+ подпадать под правовые нормы. Ответственность за соблюдение применимого
31
+ права и условий обслуживания лежит на пользователе. Авторы не несут
32
+ ответственности за последствия использования.
33
+
34
+ См. также `docs/specification.md` (раздел 11) и `docs/knowledge.md` (раздел 11).
fresta-0.2.0/PKG-INFO ADDED
@@ -0,0 +1,225 @@
1
+ Metadata-Version: 2.4
2
+ Name: fresta
3
+ Version: 0.2.0
4
+ Summary: Инструмент доступа к открытому интернету под российскими операторскими белыми списками (мобильные сети).
5
+ Author: fresta maintainers
6
+ License-Expression: MIT
7
+ Project-URL: Repository, https://github.com/VibeIDEProjects/Fresta
8
+ Project-URL: Issues, https://github.com/VibeIDEProjects/Fresta/issues
9
+ Project-URL: Habr article (zarazaex), https://habr.com/ru/articles/1027276/
10
+ Keywords: vpn,whitelist,vless,reality,russia,censorship-circumvention
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: End Users/Desktop
14
+ Classifier: Operating System :: POSIX :: Linux
15
+ Classifier: Operating System :: MacOS
16
+ Classifier: Operating System :: Microsoft :: Windows
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.8
19
+ Classifier: Programming Language :: Python :: 3.9
20
+ Classifier: Programming Language :: Python :: 3.10
21
+ Classifier: Programming Language :: Python :: 3.11
22
+ Classifier: Programming Language :: Python :: 3.12
23
+ Classifier: Topic :: Internet :: Proxy Servers
24
+ Classifier: Topic :: Security
25
+ Requires-Python: >=3.8
26
+ Description-Content-Type: text/markdown
27
+ License-File: LICENSE
28
+ Provides-Extra: dev
29
+ Requires-Dist: ruff>=0.5; extra == "dev"
30
+ Requires-Dist: mypy>=1.10; extra == "dev"
31
+ Requires-Dist: pytest>=8.0; extra == "dev"
32
+ Requires-Dist: pytest-cov>=5.0; extra == "dev"
33
+ Requires-Dist: types-requests>=2.32; extra == "dev"
34
+ Requires-Dist: build>=1.0; extra == "dev"
35
+ Requires-Dist: twine>=5.0; extra == "dev"
36
+ Dynamic: license-file
37
+
38
+ # fresta
39
+
40
+ > Свет проходит даже сквозь щель.
41
+
42
+
43
+ [![CI](https://github.com/VibeIDEProjects/Fresta/actions/workflows/tests.yml/badge.svg)](https://github.com/VibeIDEProjects/Fresta/actions/workflows/tests.yml)
44
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
45
+ [![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue.svg)](pyproject.toml)
46
+ [![stdlib-only](https://img.shields.io/badge/dependencies-stdlib--only-green.svg)](#зависимости)
47
+
48
+ > **⚠️ Badges:** CI-бейдж заработает после первого push в `main` (workflow `.github/workflows/tests.yml`).
49
+
50
+ Инструмент доступа к открытому интернету в условиях операторских **белых списков**
51
+ (РФ, мобильные сети). Идея: найти и переиспользовать «щель» — инфраструктуру, чьи IP
52
+ оператор обязан пропускать, и пустить через неё свой трафик.
53
+
54
+ Название — `fresta` (порт. «щель в ставнях, через которую пробивается свет»).
55
+
56
+ ## Как работает белый список (против чего мы)
57
+
58
+ Двухуровневая фильтрация, по умолчанию drop-all:
59
+
60
+ - **L3** — CIDR-фильтр по IP. Пакет не к разрешённой подсети дропается ещё до DPI.
61
+ - **L7** — DPI смотрит SNI в TLS ClientHello; домен в чёрном списке → RST.
62
+
63
+ Маскировка протокола (Reality, обфускация) против L3 бесполезна: блокировка идёт по
64
+ адресу назначения, до того как протокол себя проявит. Работает только транспорт,
65
+ физически идущий **на whitelisted-IP**. В РФ это прежде всего Yandex Cloud (≈каждый
66
+ пятый IP в списке), а также VK, Selectel, Timeweb, Ростелеком.
67
+
68
+ ## Структура
69
+
70
+ Код в `scripts/` разложен по **тематическим подпапкам** (recon / harvest / deploy /
71
+ relay / tests). Подробная карта — `scripts/README.md`. Кратко:
72
+
73
+ ```
74
+ fresta/
75
+ ├── README.md ← этот файл
76
+ ├── scripts/ ← код (см. scripts/README.md)
77
+ │ ├── recon/ Фаза 0: разведка (GO/NO-GO по whitelist-доменам)
78
+ │ ├── harvest/ harvest'ы: zieng2/wl (SNI) + openlibrecommunity/twl (IP)
79
+ │ ├── deploy/ Метод 1: VLESS+Reality — генер + деплой на VPS
80
+ │ ├── relay/ Метод 2: Yandex Cloud relay (handler + клиент)
81
+ │ ├── tests/ smoke-тесты (60+ кейсов) + run_tests.{sh,ps1} + probe_reality.py
82
+ │ └── README.md ← карта scripts/
83
+ └── docs/ ← документация
84
+ ├── README.md ← карта docs/
85
+ ├── knowledge.md ← прочитать первым (контекст-хэндофф)
86
+ ├── specification.md идея, threat model, архитектура
87
+ ├── ROADMAP.md чек-лист: что гонять где
88
+ └── manuals/ пошаговые гайды по методу (карта — manuals/README.md)
89
+ ├── vless-vps/ Метод 1: VLESS+Reality на VPS
90
+ │ ├── deploy.md quickstart + troubleshooting
91
+ │ └── reality-params.md
92
+ ├── ycloud-function/ Метод 2: YC Functions relay
93
+ │ └── deploy.md
94
+ └── recon/ Phase 0: разведка
95
+ └── twl-harvest.md
96
+ ```
97
+
98
+ ## Компоненты
99
+
100
+ | Файл | Что | Фаза |
101
+ |------|-----|------|
102
+ | `docs/specification.md` | Идея, threat model, архитектура, роадмап | — |
103
+ | `docs/ROADMAP.md` | Чек-лист: что сделано и что погонять где | — |
104
+ | `docs/knowledge.md` | Полный контекст-хэндофф проекта (читать первым) | — |
105
+ | `scripts/harvest/reports/harvest-report.md` | Снимок SNI/провайдеров из живой подписки zieng2/wl | — |
106
+ | `docs/manuals/vless-vps/deploy.md` | **vless-vps (Метод 1): quickstart + troubleshooting** (сценарии A/B) | 2 |
107
+ | `docs/manuals/vless-vps/reality-params.md` | Reality-параметры + генератор + ручной деплой | 2 |
108
+ | `docs/manuals/ycloud-function/deploy.md` | **ycloud-function (Метод 2): YC Functions relay + клиент** | 2 |
109
+ | `docs/manuals/recon/twl-harvest.md` | **harvest whitelisted-IP** (twl) | 0 |
110
+ | `scripts/recon/fresta_recon.py` | Recon: за каким провайдером сидят whitelisted-домены → GO/NO-GO | 0 |
111
+ | `scripts/recon/whitelist.txt` | Домены белого списка Минцифры (реконструкция по сервисам) | 0 |
112
+ | `scripts/recon/whitelist.sample.txt` | Пример формата ввода | 0 |
113
+ | `scripts/harvest/sni_candidates.txt` | Whitelisted-SNI для своего Reality-конфига (harvest) | 0 |
114
+ | `scripts/harvest/harvest_subscription.py` | Выжимает SNI + провайдеров из VLESS-подписки | 0 |
115
+ | `scripts/harvest/harvest_twl.py` | **harvest whitelisted-IP** из openlibrecommunity/twl → ips.txt / subnets.txt | 0 |
116
+ | `scripts/harvest/twl-data/` | Выход harvest'а: ips.txt (≈44k IP), subnets.txt (41 /24), report.md, meta.json | 0 |
117
+ | `scripts/deploy/fresta_gen_vless.py` | **Генератор** Xray/sing-box/vless:// для VLESS+Reality | 2 |
118
+ | `scripts/deploy/deploy_vps.sh` | **Серверный деплой** Метода 1: ставит Xray, кладёт конфиг, открывает порт, рестарт | 2 |
119
+ | `scripts/deploy/quickstart.sh` | **Локальный одноступенчатый деплой**: генер → scp → deploy → scp обратно | 2 |
120
+ | `scripts/deploy/configs/default/` | Пример сгенерированного набора (демо) | 2 |
121
+ | `scripts/deploy/configs/remote-fresta/` | PoC-набор для fresta.ru (end-to-end пройден) | 2 |
122
+ | `scripts/relay/yc_function/handler.py` | Relay-функция на Yandex Cloud (fetch-on-behalf) | 2 |
123
+ | `scripts/relay/fresta_client.py` | Локальный клиент к relay: CLI + HTTP-proxy | 2 |
124
+ | `scripts/tests/test_*.py` | Smoke-тесты (60+ кейсов), ловят регрессии | — |
125
+ | `scripts/tests/probe_reality.py` | TLS-probe ко всем whitelisted-SNI через sing-box SOCKS5 | — |
126
+ | `scripts/tests/run_tests.sh` / `.ps1` | Прогон всех тестов разом | — |
127
+
128
+ ## Статус
129
+
130
+ - ✅ Имя, концепция, спека.
131
+ - ✅ Фаза 0: recon-скрипт (цель — российские провайдеры, Yandex Cloud во главе) + список доменов. Оффлайн-логика протестирована.
132
+ - ✅ Метод 2: минимальный serverless fetch-relay. Плумбинг протестирован end-to-end.
133
+ - ✅ Фаза 2 (Метод 1): **генератор** VLESS+Reality конфигов + **deploy-скрипты** (`deploy_vps.sh` + `quickstart.sh`).
134
+ - ✅ Фаза 2 (Метод 1): **PoC end-to-end на fresta.ru** — Xray v26.3.27 + sing-box 1.13.13, `curl --proxy socks5h https://api.github.com/zen` = 200 OK, exit-IP сменился на 89.253.255.108.
135
+ - ⬜ Фаза 2: деплой и прогон на **whitelisted-VPS** под мобильным каналом с белым списком.
136
+ - ⬜ Фаза 3: ротация фронтов (несколько VPS × несколько SNI × автоперебор).
137
+ - ✅ Подключить реальные whitelisted-IP: `scripts/harvest/harvest_twl.py` (43k+ IP из openlibrecommunity/twl).
138
+ - ⬜ Подключить реальные whitelisted-SNI под своего оператора (выжимка из twl по доменам — в планах).
139
+
140
+ ## Быстрый старт
141
+
142
+ ### Деплой Метода 1 (VLESS+Reality) одной командой
143
+
144
+ ```bash
145
+ # Из корня репо. Скрипт сам сгенерит конфиги, зальёт на VPS, поставит Xray,
146
+ # откроет порт, рестартанёт сервис и вернёт client.json / links.txt тебе.
147
+ bash scripts/deploy/quickstart.sh --ssh user@your-vps.example.com
148
+ # Подробности, опции, troubleshooting — docs/manuals/vless-vps/deploy.md
149
+ ```
150
+
151
+ **Нет whitelisted-VPS под рукой?** Используй **любой** доступный сервер — quickstart
152
+ такой же, архитектура работает, но под белым списком оператора пройдёт **только**
153
+ когда IP-адрес будет в whitelisted-подсети. PoC на fresta.ru: 89.253.255.108 — end-to-end
154
+ пройден, см. `scripts/deploy/configs/remote-fresta/` и `docs/ROADMAP.md`.
155
+
156
+ ### Остальное (по компонентам)
157
+
158
+ ```bash
159
+ # Фаза 0 — есть ли щель у твоего оператора (запускать под мобильным каналом)
160
+ python3 scripts/recon/fresta_recon.py scripts/recon/whitelist.txt --probe
161
+
162
+ # Метод 2 — проверить канал (деплой и детали в docs/manuals/ycloud-function/deploy.md)
163
+ python3 scripts/relay/fresta_client.py --check
164
+
165
+ # Фаза 2 (Метод 1) — сгенерировать конфиги без деплоя (например, для теста)
166
+ python3 scripts/deploy/fresta_gen_vless.py --exit-ip ВАШ.IP.ЛИТЕРАЛ --out configs/my-vps
167
+
168
+ # Фаза 0 — реальные whitelisted-IP от openlibrecommunity/twl (≈44k IP, 498 ASN)
169
+ python3 scripts/harvest/harvest_twl.py # полный harvest
170
+ python3 scripts/harvest/harvest_twl.py --providers yandex --min-subnet-density 0.7 # фильтр
171
+
172
+ # Smoke-тесты (60+ кейсов — ловят регрессии в recon/handler/gen_vless/harvest/twl)
173
+ bash scripts/tests/run_tests.sh # Linux / macOS / WSL / Git Bash
174
+ powershell scripts/tests/run_tests.ps1 # Windows PowerShell
175
+ ```
176
+
177
+ ### Импорт `client.json` в sing-box
178
+
179
+ ```bash
180
+ # Linux/macOS/WSL
181
+ mkdir -p ~/.config/sing-box
182
+ cp scripts/deploy/configs/<host>-<date>/client.json ~/.config/sing-box/config.json
183
+ sing-box check -c ~/.config/sing-box/config.json
184
+ sing-box run -c ~/.config/sing-box/config.json &
185
+ curl --proxy socks5h://127.0.0.1:1080 https://api.github.com/zen # 200 OK
186
+ ```
187
+
188
+ > **На Windows:** используй Git Bash или WSL для bash-скриптов; для sing-box есть
189
+ > `winget install SagerNet.sing-box`.
190
+
191
+ ## Методы обхода (от простого к сложному)
192
+
193
+ 1. **VLESS + Reality на РФ-VPS** — основной, стабильный. IP в whitelist + whitelisted-SNI + `fp=chrome`.
194
+ 2. **Yandex Cloud Functions** (этот репо, Метод 2) — serverless fetch-relay, бесплатно, но не туннель.
195
+ 3. **API Gateway + WebSocket → VPS** — настоящий туннель; вектор уже начали банить.
196
+ 4. **olcRTC / xDNS** — экспериментальные (видеозвонки, DNS); см. openlibrecommunity.
197
+
198
+ Подробный разбор уровней фильтрации и методов — в `docs/specification.md` и статье
199
+ zarazaex на Хабре (habr.com/ru/articles/1027276).
200
+
201
+ ## Зависимости
202
+
203
+ **Рантайм — stdlib-only.** Никаких `pip install` для пользователя; только Python 3.8+
204
+ (и `openssl` для X25519, `ssh`/`scp` для деплоя). Это сознательное решение: минимум
205
+ поверхности атаки, нулевая стоимость входа, одинаково работает на любом VPS.
206
+
207
+ **Dev-стек** (опционально, для контрибьюторов): `ruff` + `mypy` + `pytest` —
208
+ поднимается одной командой:
209
+ ```bash
210
+ pip install -e .[dev]
211
+ make lint test
212
+ ```
213
+
214
+ ## Для контрибьюторов
215
+
216
+ - Читай [`CONTRIBUTING.md`](CONTRIBUTING.md) — там workflow, правила приёма PR, что НЕ принимаем.
217
+ - История изменений — [`CHANGELOG.md`](CHANGELOG.md).
218
+ - Лицензия — [`LICENSE`](LICENSE) (MIT).
219
+ - Issues — шаблоны [bug report](.github/ISSUE_TEMPLATE/bug_report.yml) и [feature request](.github/ISSUE_TEMPLATE/feature_request.yml).
220
+
221
+ ## Рамка
222
+
223
+ Обход операторских ограничений и проксирование через чужой serverless — серая зона и
224
+ нарушение ToS провайдеров (функции/серверы сносят, идёт арм-рейс). Инструмент — для
225
+ доступа к открытому интернету; оценка рисков и решение на пользователе.
fresta-0.2.0/README.md ADDED
@@ -0,0 +1,188 @@
1
+ # fresta
2
+
3
+ > Свет проходит даже сквозь щель.
4
+
5
+
6
+ [![CI](https://github.com/VibeIDEProjects/Fresta/actions/workflows/tests.yml/badge.svg)](https://github.com/VibeIDEProjects/Fresta/actions/workflows/tests.yml)
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
8
+ [![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue.svg)](pyproject.toml)
9
+ [![stdlib-only](https://img.shields.io/badge/dependencies-stdlib--only-green.svg)](#зависимости)
10
+
11
+ > **⚠️ Badges:** CI-бейдж заработает после первого push в `main` (workflow `.github/workflows/tests.yml`).
12
+
13
+ Инструмент доступа к открытому интернету в условиях операторских **белых списков**
14
+ (РФ, мобильные сети). Идея: найти и переиспользовать «щель» — инфраструктуру, чьи IP
15
+ оператор обязан пропускать, и пустить через неё свой трафик.
16
+
17
+ Название — `fresta` (порт. «щель в ставнях, через которую пробивается свет»).
18
+
19
+ ## Как работает белый список (против чего мы)
20
+
21
+ Двухуровневая фильтрация, по умолчанию drop-all:
22
+
23
+ - **L3** — CIDR-фильтр по IP. Пакет не к разрешённой подсети дропается ещё до DPI.
24
+ - **L7** — DPI смотрит SNI в TLS ClientHello; домен в чёрном списке → RST.
25
+
26
+ Маскировка протокола (Reality, обфускация) против L3 бесполезна: блокировка идёт по
27
+ адресу назначения, до того как протокол себя проявит. Работает только транспорт,
28
+ физически идущий **на whitelisted-IP**. В РФ это прежде всего Yandex Cloud (≈каждый
29
+ пятый IP в списке), а также VK, Selectel, Timeweb, Ростелеком.
30
+
31
+ ## Структура
32
+
33
+ Код в `scripts/` разложен по **тематическим подпапкам** (recon / harvest / deploy /
34
+ relay / tests). Подробная карта — `scripts/README.md`. Кратко:
35
+
36
+ ```
37
+ fresta/
38
+ ├── README.md ← этот файл
39
+ ├── scripts/ ← код (см. scripts/README.md)
40
+ │ ├── recon/ Фаза 0: разведка (GO/NO-GO по whitelist-доменам)
41
+ │ ├── harvest/ harvest'ы: zieng2/wl (SNI) + openlibrecommunity/twl (IP)
42
+ │ ├── deploy/ Метод 1: VLESS+Reality — генер + деплой на VPS
43
+ │ ├── relay/ Метод 2: Yandex Cloud relay (handler + клиент)
44
+ │ ├── tests/ smoke-тесты (60+ кейсов) + run_tests.{sh,ps1} + probe_reality.py
45
+ │ └── README.md ← карта scripts/
46
+ └── docs/ ← документация
47
+ ├── README.md ← карта docs/
48
+ ├── knowledge.md ← прочитать первым (контекст-хэндофф)
49
+ ├── specification.md идея, threat model, архитектура
50
+ ├── ROADMAP.md чек-лист: что гонять где
51
+ └── manuals/ пошаговые гайды по методу (карта — manuals/README.md)
52
+ ├── vless-vps/ Метод 1: VLESS+Reality на VPS
53
+ │ ├── deploy.md quickstart + troubleshooting
54
+ │ └── reality-params.md
55
+ ├── ycloud-function/ Метод 2: YC Functions relay
56
+ │ └── deploy.md
57
+ └── recon/ Phase 0: разведка
58
+ └── twl-harvest.md
59
+ ```
60
+
61
+ ## Компоненты
62
+
63
+ | Файл | Что | Фаза |
64
+ |------|-----|------|
65
+ | `docs/specification.md` | Идея, threat model, архитектура, роадмап | — |
66
+ | `docs/ROADMAP.md` | Чек-лист: что сделано и что погонять где | — |
67
+ | `docs/knowledge.md` | Полный контекст-хэндофф проекта (читать первым) | — |
68
+ | `scripts/harvest/reports/harvest-report.md` | Снимок SNI/провайдеров из живой подписки zieng2/wl | — |
69
+ | `docs/manuals/vless-vps/deploy.md` | **vless-vps (Метод 1): quickstart + troubleshooting** (сценарии A/B) | 2 |
70
+ | `docs/manuals/vless-vps/reality-params.md` | Reality-параметры + генератор + ручной деплой | 2 |
71
+ | `docs/manuals/ycloud-function/deploy.md` | **ycloud-function (Метод 2): YC Functions relay + клиент** | 2 |
72
+ | `docs/manuals/recon/twl-harvest.md` | **harvest whitelisted-IP** (twl) | 0 |
73
+ | `scripts/recon/fresta_recon.py` | Recon: за каким провайдером сидят whitelisted-домены → GO/NO-GO | 0 |
74
+ | `scripts/recon/whitelist.txt` | Домены белого списка Минцифры (реконструкция по сервисам) | 0 |
75
+ | `scripts/recon/whitelist.sample.txt` | Пример формата ввода | 0 |
76
+ | `scripts/harvest/sni_candidates.txt` | Whitelisted-SNI для своего Reality-конфига (harvest) | 0 |
77
+ | `scripts/harvest/harvest_subscription.py` | Выжимает SNI + провайдеров из VLESS-подписки | 0 |
78
+ | `scripts/harvest/harvest_twl.py` | **harvest whitelisted-IP** из openlibrecommunity/twl → ips.txt / subnets.txt | 0 |
79
+ | `scripts/harvest/twl-data/` | Выход harvest'а: ips.txt (≈44k IP), subnets.txt (41 /24), report.md, meta.json | 0 |
80
+ | `scripts/deploy/fresta_gen_vless.py` | **Генератор** Xray/sing-box/vless:// для VLESS+Reality | 2 |
81
+ | `scripts/deploy/deploy_vps.sh` | **Серверный деплой** Метода 1: ставит Xray, кладёт конфиг, открывает порт, рестарт | 2 |
82
+ | `scripts/deploy/quickstart.sh` | **Локальный одноступенчатый деплой**: генер → scp → deploy → scp обратно | 2 |
83
+ | `scripts/deploy/configs/default/` | Пример сгенерированного набора (демо) | 2 |
84
+ | `scripts/deploy/configs/remote-fresta/` | PoC-набор для fresta.ru (end-to-end пройден) | 2 |
85
+ | `scripts/relay/yc_function/handler.py` | Relay-функция на Yandex Cloud (fetch-on-behalf) | 2 |
86
+ | `scripts/relay/fresta_client.py` | Локальный клиент к relay: CLI + HTTP-proxy | 2 |
87
+ | `scripts/tests/test_*.py` | Smoke-тесты (60+ кейсов), ловят регрессии | — |
88
+ | `scripts/tests/probe_reality.py` | TLS-probe ко всем whitelisted-SNI через sing-box SOCKS5 | — |
89
+ | `scripts/tests/run_tests.sh` / `.ps1` | Прогон всех тестов разом | — |
90
+
91
+ ## Статус
92
+
93
+ - ✅ Имя, концепция, спека.
94
+ - ✅ Фаза 0: recon-скрипт (цель — российские провайдеры, Yandex Cloud во главе) + список доменов. Оффлайн-логика протестирована.
95
+ - ✅ Метод 2: минимальный serverless fetch-relay. Плумбинг протестирован end-to-end.
96
+ - ✅ Фаза 2 (Метод 1): **генератор** VLESS+Reality конфигов + **deploy-скрипты** (`deploy_vps.sh` + `quickstart.sh`).
97
+ - ✅ Фаза 2 (Метод 1): **PoC end-to-end на fresta.ru** — Xray v26.3.27 + sing-box 1.13.13, `curl --proxy socks5h https://api.github.com/zen` = 200 OK, exit-IP сменился на 89.253.255.108.
98
+ - ⬜ Фаза 2: деплой и прогон на **whitelisted-VPS** под мобильным каналом с белым списком.
99
+ - ⬜ Фаза 3: ротация фронтов (несколько VPS × несколько SNI × автоперебор).
100
+ - ✅ Подключить реальные whitelisted-IP: `scripts/harvest/harvest_twl.py` (43k+ IP из openlibrecommunity/twl).
101
+ - ⬜ Подключить реальные whitelisted-SNI под своего оператора (выжимка из twl по доменам — в планах).
102
+
103
+ ## Быстрый старт
104
+
105
+ ### Деплой Метода 1 (VLESS+Reality) одной командой
106
+
107
+ ```bash
108
+ # Из корня репо. Скрипт сам сгенерит конфиги, зальёт на VPS, поставит Xray,
109
+ # откроет порт, рестартанёт сервис и вернёт client.json / links.txt тебе.
110
+ bash scripts/deploy/quickstart.sh --ssh user@your-vps.example.com
111
+ # Подробности, опции, troubleshooting — docs/manuals/vless-vps/deploy.md
112
+ ```
113
+
114
+ **Нет whitelisted-VPS под рукой?** Используй **любой** доступный сервер — quickstart
115
+ такой же, архитектура работает, но под белым списком оператора пройдёт **только**
116
+ когда IP-адрес будет в whitelisted-подсети. PoC на fresta.ru: 89.253.255.108 — end-to-end
117
+ пройден, см. `scripts/deploy/configs/remote-fresta/` и `docs/ROADMAP.md`.
118
+
119
+ ### Остальное (по компонентам)
120
+
121
+ ```bash
122
+ # Фаза 0 — есть ли щель у твоего оператора (запускать под мобильным каналом)
123
+ python3 scripts/recon/fresta_recon.py scripts/recon/whitelist.txt --probe
124
+
125
+ # Метод 2 — проверить канал (деплой и детали в docs/manuals/ycloud-function/deploy.md)
126
+ python3 scripts/relay/fresta_client.py --check
127
+
128
+ # Фаза 2 (Метод 1) — сгенерировать конфиги без деплоя (например, для теста)
129
+ python3 scripts/deploy/fresta_gen_vless.py --exit-ip ВАШ.IP.ЛИТЕРАЛ --out configs/my-vps
130
+
131
+ # Фаза 0 — реальные whitelisted-IP от openlibrecommunity/twl (≈44k IP, 498 ASN)
132
+ python3 scripts/harvest/harvest_twl.py # полный harvest
133
+ python3 scripts/harvest/harvest_twl.py --providers yandex --min-subnet-density 0.7 # фильтр
134
+
135
+ # Smoke-тесты (60+ кейсов — ловят регрессии в recon/handler/gen_vless/harvest/twl)
136
+ bash scripts/tests/run_tests.sh # Linux / macOS / WSL / Git Bash
137
+ powershell scripts/tests/run_tests.ps1 # Windows PowerShell
138
+ ```
139
+
140
+ ### Импорт `client.json` в sing-box
141
+
142
+ ```bash
143
+ # Linux/macOS/WSL
144
+ mkdir -p ~/.config/sing-box
145
+ cp scripts/deploy/configs/<host>-<date>/client.json ~/.config/sing-box/config.json
146
+ sing-box check -c ~/.config/sing-box/config.json
147
+ sing-box run -c ~/.config/sing-box/config.json &
148
+ curl --proxy socks5h://127.0.0.1:1080 https://api.github.com/zen # 200 OK
149
+ ```
150
+
151
+ > **На Windows:** используй Git Bash или WSL для bash-скриптов; для sing-box есть
152
+ > `winget install SagerNet.sing-box`.
153
+
154
+ ## Методы обхода (от простого к сложному)
155
+
156
+ 1. **VLESS + Reality на РФ-VPS** — основной, стабильный. IP в whitelist + whitelisted-SNI + `fp=chrome`.
157
+ 2. **Yandex Cloud Functions** (этот репо, Метод 2) — serverless fetch-relay, бесплатно, но не туннель.
158
+ 3. **API Gateway + WebSocket → VPS** — настоящий туннель; вектор уже начали банить.
159
+ 4. **olcRTC / xDNS** — экспериментальные (видеозвонки, DNS); см. openlibrecommunity.
160
+
161
+ Подробный разбор уровней фильтрации и методов — в `docs/specification.md` и статье
162
+ zarazaex на Хабре (habr.com/ru/articles/1027276).
163
+
164
+ ## Зависимости
165
+
166
+ **Рантайм — stdlib-only.** Никаких `pip install` для пользователя; только Python 3.8+
167
+ (и `openssl` для X25519, `ssh`/`scp` для деплоя). Это сознательное решение: минимум
168
+ поверхности атаки, нулевая стоимость входа, одинаково работает на любом VPS.
169
+
170
+ **Dev-стек** (опционально, для контрибьюторов): `ruff` + `mypy` + `pytest` —
171
+ поднимается одной командой:
172
+ ```bash
173
+ pip install -e .[dev]
174
+ make lint test
175
+ ```
176
+
177
+ ## Для контрибьюторов
178
+
179
+ - Читай [`CONTRIBUTING.md`](CONTRIBUTING.md) — там workflow, правила приёма PR, что НЕ принимаем.
180
+ - История изменений — [`CHANGELOG.md`](CHANGELOG.md).
181
+ - Лицензия — [`LICENSE`](LICENSE) (MIT).
182
+ - Issues — шаблоны [bug report](.github/ISSUE_TEMPLATE/bug_report.yml) и [feature request](.github/ISSUE_TEMPLATE/feature_request.yml).
183
+
184
+ ## Рамка
185
+
186
+ Обход операторских ограничений и проксирование через чужой serverless — серая зона и
187
+ нарушение ToS провайдеров (функции/серверы сносят, идёт арм-рейс). Инструмент — для
188
+ доступа к открытому интернету; оценка рисков и решение на пользователе.
fresta-0.2.0/fresta/__init__.py ADDED
@@ -0,0 +1,26 @@
1
+ """fresta · инструмент доступа к открытому интернету под российскими операторскими
2
+ белыми списками (мобильные сети).
3
+
4
+ Метапакет: содержит только версию и метаинформацию. Вся функциональность
5
+ лежит в `scripts/` и доступна через CLI-скрипты (см. pyproject.toml
6
+ После `pip install fresta` пользователь
7
+ получает в PATH: `fresta-recon`, `fresta-harvest-sni`, `fresta-gen-vless`,
8
+ `fresta-validate`, `fresta-sanity`, `fresta-diff` и т.д.
9
+
10
+ Использование:
11
+ import fresta
12
+ print(fresta.__version__)
13
+ print(fresta.__doc__)
14
+ """
15
+
16
+ # `__version__` синхронизирован с [project.version] в pyproject.toml.
17
+ # Должен быть ОДИН источник правды — сейчас это pyproject.toml,
18
+ # и сюда мы его копируем руками при bump (см. docs/PUBLISH.md).
19
+ __version__ = "0.2.0"
20
+
21
+ # Краткое описание для `python -c "import fresta; help(fresta)"`
22
+ __summary__ = "Обход операторских IP-белых списков через whitelisted-инфраструктуру (Yandex Cloud, РФ-VPS)"
23
+
24
+ # Маркеры, помогающие авто-тестам/докам понять, что это не библиотека для импорта,
25
+ # а набор CLI-скриптов.
26
+ __all__ = ["__version__", "__summary__"]
fresta-0.2.0/fresta/py.typed ADDED
@@ -0,0 +1,6 @@
1
+ # Marker file for PEP 561 — signals type-checkers (mypy, pyright) that
2
+ # the fresta package supports type hints. The package itself has minimal
3
+ # runtime API (only `__version__` / `__summary__`); type-checkers should
4
+ # not complain about missing stubs.
5
+ #
6
+ # См. https://peps.python.org/pep-0561/ — пакет публикуется без `fresta-stubs`.