Scepter

EN | RU

GPL-3.0 open-source fork / analog of Throne: Qt6 desktop GUI + Go core embedding sing-box, with macOS TUN done the Apple way (Network Extension Packet Tunnel Provider).

Provisional name. Rename is welcome before public launch.

Goals

macOS-first real tunnel mode (not System Proxy–only MVP)
Proper privilege model: no setuid Core inside the .app, no Terminal/osascript escalation UX
Thin Qt6 GUI; Go daemon/library for proxy logic
Prefer upstream sing-box; document temporary Throne forks only if needed for feature parity
Windows / Linux later

Product intent (for Apple / reviewers)

Time2VPN (repo name: Scepter) is a macOS VPN client. It configures and runs a user-consented VPN tunnel via Apple’s standard Network Extension APIs — specifically a Packet Tunnel Provider (NETunnelProviderManager / NEPacketTunnelProvider / NEPacketTunnelFlow). It is not adware, and it is not designed to conceal malicious behavior.

Topic	Fact
What it is	Desktop VPN / proxy client (profiles, routing, start/stop tunnel). Display name Time2VPN; bundle id `com.time2map.vpn`.
Open source	Licensed under GNU GPL v3. Source is intended for a public repository. Reviewers and users can inspect the full client, tunnel host, and core — there is no closed “malware payload” beside the published code.
Why it exists	Built originally as internal company VPN tooling for employees/colleagues — legitimate remote-access / traffic-routing software, not mass shady distribution of unsigned “suspicious” apps.
Apple APIs	Uses documented Network Extension Packet Tunnel entitlements and the system VPN UX (user grants VPN permission in System Settings).
Distribution	Outside the Mac App Store: Developer ID signing + notarization (see DMG packaging below), so colleagues can run a Gatekeeper-clean build without each needing their own Apple Team. An App Store Connect record may exist for identifiers; this README does not claim a Mac App Store listing.
Not malware	No intent to act as malware, adware, ransomware, or a covert persistence/exfiltration tool. Tunnel traffic follows user-selected profiles and routes; privilege model avoids setuid-in-`.app` and Terminal/`osascript` escalation.

Technical process boundaries: ARCHITECTURE.md.

macOS TUN / Network Extension (hard requirements)

Working tunnel on modern macOS requires:

Requirement	Why
Apple Developer Program membership	Packet Tunnel entitlements are not available ad-hoc
App ID + Network Extension capability (`packet-tunnel-provider`)	Apple-correct VPN path
App Group	Share config / socket paths between GUI and extension
Provisioning profiles (dev + release)	Sign appex + containing app
Developer ID + notarization (outside Mac App Store)	Gatekeeper / distribution
Native (Swift/ObjC++) host for `NETunnelProviderManager`	Qt alone cannot configure NE

See ARCHITECTURE.md for process boundaries and rationale.

Build status (Phase 1)

Compilable skeleton with real Xcode targets + Go c-archive stub ABI. VPN will not run until you set a Team ID and provision Network Extension + App Groups.

Piece	Status
Go `libscepter_core.a` (stub engine)	Builds (`./daemon/core/scripts/build_carchive.sh`)
Xcode app + Packet Tunnel appex	Builds unsigned (`xcodegen` + `xcodebuild`)
Swift packet pump ↔ Go ABI	Wired (stub echoes packets)
Profiles / routes SQLite + share-link import (Swift)	Working in `apps/macos-tunnel` — see `docs/SCHEMA.md`
Qt6 desktop shell + NE bridge	Builds (`cmake` + Ninja); Start/Stop wired to `ScepterNEBridge`
sing-box embed	TODO — ABI shaped for clean plug-in

Identifiers (App Store Connect / portal)

ASC app record alone is not enough for Network Extension signing. Owner/admin must also create App IDs + App Group under Certificates, Identifiers & Profiles.

Item	Value
Display name	Time2VPN / time2vpn (“VPN with TUN”)
App (main)	`com.time2map.vpn`
Tunnel appex	`com.time2map.vpn.tunnel` (conventional — create on developer.apple.com if missing)
App Group	`group.com.time2map.vpn` (create/enable and assign to both App IDs)
ASC Apple ID	`6792749221`
SKU	`vpnwithtun`
`DEVELOPMENT_TEAM`	empty — set in Xcode (do not invent)

Portal checklist (owner/admin)

App ID com.time2map.vpn — enable Network Extensions (Packet Tunnel) + App Groups.
App ID com.time2map.vpn.tunnel — enable Packet Tunnel + App Groups (required for the appex; ASC does not create this automatically).
App Group group.com.time2map.vpn — create and assign to both App IDs.
Without the extension App ID + shared group, Xcode Signing for Packet Tunnel will still fail.

How to set Team ID in Xcode

open apps/macos-tunnel/Scepter.xcodeproj (generate first — see below).
Select project Scepter → targets Scepter and PacketTunnel.
Signing & Capabilities → Automatically manage signing → pick your paid Program team (not Personal Team).
Ensure capabilities: Network Extensions (Packet Tunnel) + App Groups (group.com.time2map.vpn).
On developer.apple.com: complete the portal checklist above if Xcode cannot create the IDs.
Real Team ID is 10 characters under Membership details — optional: set DEVELOPMENT_TEAM in apps/macos-tunnel/project.yml, then xcodegen generate.

Do not commit secrets / .p12 / provisioning profiles.

Troubleshooting: only Personal Team in Signing picker

Network Extension requires a paid Apple Developer Program team. Personal Team cannot provision Packet Tunnel.

If Accounts shows an org team (Admin) but Signing & Capabilities only lists Personal Team:

Likely cause	What to do
Membership is Individual (ASC Admin ≠ Program signing access)	Convert to Organization, or Account Holder signs
Missing Access to Certificates, Identifiers & Profiles	App Store Connect → Users and Access → enable for your user
Expired Program / pending agreements	Renew + accept on developer.apple.com
No Apple Development cert locally	Accounts → team → Manage Certificates → + → Apple Development
Stale account cache	Remove Apple ID in Accounts, re-add; reopen project

Full click-by-click: apps/macos-tunnel/README.md → Only Personal Team visible.

Desktop deps (Homebrew, arm64)

Qt is the portable UI. macOS TUN still needs the Swift Network Extension host (apps/macos-tunnel); Windows/Linux will use other privileged helpers later.

# Desktop / Qt toolchain (once)
brew install cmake ninja pkg-config qtbase qttools

# Core / NE host tools (once; often already present)
brew install go xcodegen protobuf
# Optional: sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

Tool	Path after install (Apple Silicon)
`qmake` / `qmake6`	`/opt/homebrew/opt/qtbase/bin/qmake` (also `/opt/homebrew/bin/qmake`)
`qtpaths` / `qtpaths6`	`/opt/homebrew/opt/qtbase/bin/qtpaths`
`CMAKE_PREFIX_PATH`	`$(brew --prefix qtbase)` — e.g. `/opt/homebrew/opt/qtbase`
Qt version (checked)	6.11.1 via `qtbase` + `qttools` (modular; prefer over full `qt` / WebEngine)

brew install qt (alias qt@6) also provides Qt 6.11.x but pulls many extra modules.

Build order

# One-shot helper (NE / Go path):
./scripts/build_phase1.sh

# Or manually:
# 1) Go c-archive (arm64 default; ARCH=amd64 or ARCH=arm64,amd64 for universal)
cd daemon/core && ./scripts/build_carchive.sh

# 2) Generate Xcode project (Swift NE host — keep this; do not replace with Qt)
cd ../apps/macos-tunnel && xcodegen generate
open Scepter.xcodeproj
# → set Team → Product → Build / Run

# 3) Qt desktop shell (Time2VPN window + NE bridge on macOS)
cmake -S apps/desktop -B build/desktop -G Ninja \
  -DCMAKE_PREFIX_PATH="$(brew --prefix qtbase)" \
  -DSCEPTER_ENABLE_QT=ON \
  -DSCEPTER_ENABLE_NE_BRIDGE=ON
cmake --build build/desktop
./build/desktop/scepter_desktop

# 4) Optional: protobuf stubs
./scripts/generate_proto.sh

Package macOS DMG (Time2VPN)

./scripts/make_dmg.sh
# → dist/Time2VPN-<version>-macos.dmg

Builds Go c-archive → xcodegen → Release Time2VPN.app → Developer ID codesign (if available) → hdiutil DMG → optional notarization (NOTARY_PROFILE or ASC API key env vars).

Distribution honesty: without Developer ID Application + notarization, the DMG is convenient but colleagues will often hit Gatekeeper / Network Extension blocks. With Developer ID + notarytool + staple, colleagues usually do not need their own Apple Team. Details: apps/macos-tunnel/README.md → Package DMG, and comments in scripts/make_dmg.sh.

Details: apps/desktop/README.md.

Unsigned compile check (no Team yet):

export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
cd apps/macos-tunnel
xcodebuild -scheme Scepter -destination 'platform=macOS,arch=arm64' \
  CODE_SIGNING_ALLOWED=NO build

Layout

apps/desktop/          Qt6 Time2VPN shell + macOS ObjC++ NE bridge (ScepterNEBridge)
apps/macos-tunnel/     XcodeGen project: Scepter.app + PacketTunnel.appex (NE host — keep)
daemon/core/           Go module, cgo ABI, c-archive build
protocol/scepter/v1/   scepter.v1 protobuf
docs/                  porting / sing-box fork notes / SCHEMA.md

Architecture: Swift NE vs Qt UI

Layer	Role
Qt (`apps/desktop`)	Cross-platform UI (profiles, Start/Stop). Portable to Windows/Linux later.
Swift NE host (`apps/macos-tunnel`)	Required on macOS: installs/starts Packet Tunnel via `NETunnelProviderManager`. Profiles/routes SQLite + config generation live here first.
Packet Tunnel `.appex`	Owns TUN / `NEPacketTunnelFlow` + Go `c-archive` (sing-box).
Windows/Linux (later)	Different privileged helpers — not Network Extension; same Qt UI + protobuf control API.

Qt Start/Stop buttons call apps/desktop/src/macos/ScepterNEBridge.h (scepter_ne_start / stop / write_active_config). Runtime VPN still needs a signed Team ID + App Group.

Profiles / routing (Swift host — current)

The AppKit shell (apps/macos-tunnel) now has working Throne-like profile management:

SQLite store (groups, profiles, route profiles/rules, remote rule-sets, settings) — schema in docs/SCHEMA.md
Add / Edit / Delete profiles; import ss:// vmess:// vless:// trojan:// hy2:// socks:// share links
Routing window: route profiles + domain/IP/process/rule_set rules; remote .srs catalog (enable / download / add URL)
On Start: selected profile + route + enabled rule-sets → sing-box JSON → App Group active-config.json + tunnel start options

Default remote rule-set URLs (Throne / MetaCubeX)

Seeded disabled until you enable + Download in Routing. Canonical sources match Throne’s srslist.h (routeprofiles rule-set) plus extras from the routeprofiles release (Antizapret / Re-filter) and AdBlock. Downloads use the Cloudflare jsDelivr mirror (testingcf.jsdelivr.net), same as Throne’s default.

Curated catalog (~69 presets): CN/GFW, Iran/Russia regional lists, private/ads, popular services (google, telegram, netflix, youtube, openai, …), plus antizapret / refilter-*. Full Throne list is ~2174 tags — use Add URL… for the rest. Manage Routes has a tag/URL filter.

Category	Example tags
CN / GFW	`geoip-cn`, `geosite-cn`, `geosite-gfw`, `geosite-greatfire`, `geosite-category-anticensorship`
Iran / Russia	`geoip-ir`, `geosite-ir`, `geoip-ru`, `geosite-ru-blocked`, …
Ads / private	`geosite-category-ads-all`, `geoip-private`, `scepter-adblocksingbox`
Services	`geosite-google`, `geosite-telegram`, `geosite-netflix`, `geosite-openai`, …
Release extras	`antizapret`, `refilter-domains`, `refilter-ip`

Cached files: App Group rule-sets/<tag>.srs. Generated config prefers type: local when the file exists; otherwise Throne-style type: remote.

Qt profile CRUD is still a later port; core remains a stub until sing-box is embedded.

Relation to Throne

License: GPL-3.0 inherited intentionally (copy of Throne’s LICENSE).
Not a blind code dump: clean skeleton + porting map in docs/PORT_FROM_THRONE.md.
Concepts reused later: profile/route SQLite ideas, protobuf-style control API, sing-box config generation patterns.

License

GNU GPL v3

Scepter (RU)

GPL-3.0 форк / аналог Throne: тонкий Qt6 GUI + Go-ядро на базе sing-box, с нормальным TUN на macOS через Network Extension (Packet Tunnel Provider).

Имя временное. Можно переименовать до публичного релиза.

Цели

Сначала macOS, и сразу рабочий туннель (не MVP только на System Proxy)
Без setuid внутри .app и без эскалации через Terminal / osascript
Qt6 — UI; Go — прокси-логика
По возможности upstream sing-box; форки Throne — только если нужны для паритета фич

Назначение продукта (для Apple / ревьюеров)

Time2VPN (репозиторий: Scepter) — VPN-клиент для macOS. Туннель поднимается через стандартные API Apple Network Extension — Packet Tunnel Provider (NETunnelProviderManager / NEPacketTunnelProvider / NEPacketTunnelFlow). Это не adware и не средство сокрытия вредоносного поведения.

Тема	Факт
Что это	Десктопный VPN / proxy-клиент (профили, маршруты, Start/Stop). Display name Time2VPN; bundle id `com.time2map.vpn`.
Open source	Лицензия GNU GPL v3. Исходники рассчитаны на публичный репозиторий: клиент, NE-host и ядро можно проверить целиком — отдельного закрытого «malware payload» нет.
Зачем	Изначально — внутренняя корпоративная VPN-утилита для сотрудников/коллег: легитимный remote access / маршрутизация трафика, а не массовая раздача сомнительного неподписанного ПО.
API Apple	Документированные entitlements Packet Tunnel и системный VPN UX (пользователь один раз разрешает VPN в Системных настройках).
Дистрибуция	Вне Mac App Store: подпись Developer ID + нотаризация (см. сборку DMG ниже), чтобы коллеги получали сборку, совместимую с Gatekeeper, без собственной Apple Team. Запись в App Store Connect может существовать для идентификаторов; этот README не утверждает публикацию в Mac App Store.
Не malware	Нет намерения быть malware, adware, ransomware или скрытым средством persistence/эксфильтрации. Трафик идёт по выбранным пользователем профилям и маршрутам; без setuid внутри `.app` и без эскалации через Terminal/`osascript`.

Границы процессов: ARCHITECTURE.md.

Статус Phase 1

Собираются Go c-archive (stub), Xcode-проект (app + Packet Tunnel) и Qt6-оболочка (apps/desktop). Для запуска VPN нужно выставить Team ID платной команды Apple Developer Program в Xcode и включить Network Extension + App Groups.

Зависимости desktop (Homebrew, arm64)

Qt — переносимый UI. TUN на macOS по-прежнему требует Swift Network Extension (apps/macos-tunnel); Windows/Linux позже — свои privileged helpers.

brew install cmake ninja pkg-config qtbase qttools
brew install go xcodegen protobuf   # если ещё нет

Инструмент	Путь (Apple Silicon)
`qmake` / `qtpaths`	`/opt/homebrew/opt/qtbase/bin/qmake`, `.../qtpaths`
`CMAKE_PREFIX_PATH`	`$(brew --prefix qtbase)`
Версия Qt	6.11.1 (`qtbase` + `qttools`)

Сборка Qt-приложения

cmake -S apps/desktop -B build/desktop -G Ninja \
  -DCMAKE_PREFIX_PATH="$(brew --prefix qtbase)" \
  -DSCEPTER_ENABLE_QT=ON \
  -DSCEPTER_ENABLE_NE_BRIDGE=ON
cmake --build build/desktop
./build/desktop/scepter_desktop

DMG для macOS (Time2VPN)

./scripts/make_dmg.sh
# → dist/Time2VPN-<версия>-macos.dmg

Честно: если на машине сборки нет сертификата Developer ID Application и нотаризации — DMG удобно отдать, но у коллег Gatekeeper / Network Extension часто не дадут поднять VPN. Это не «заработает у всех». С Developer ID + notarytool + staple коллегам обычно не нужна своя Apple Team. Подробности: apps/macos-tunnel/README.md и комментарии в scripts/make_dmg.sh.

Подробнее: apps/desktop/README.md.

Архитектура: Swift NE vs Qt UI

Слой	Роль
Qt (`apps/desktop`)	Кроссплатформенный UI; позже Windows/Linux
Swift NE host	Обязателен на macOS для Packet Tunnel; сейчас здесь SQLite-профили/маршруты и генерация sing-box JSON
`.appex` + Go	TUN и sing-box in-process
Windows/Linux	Другие helpers; тот же Qt + protobuf

В AppKit-оболочке (apps/macos-tunnel) уже есть Add/Edit/Delete профилей, импорт share-link, редактор маршрутов, удалённые rule-set (.srs), и запись active-config.json при Start. Схема: docs/SCHEMA.md. Ядро по-прежнему stub до embed sing-box; Qt CRUD — позже.

Дефолтные URL rule-set (как у Throne / MetaCubeX)

Кураторский каталог (~69 пресетов): CN/GFW, Iran/Russia, ads/private, популярные сервисы, плюс antizapret / refilter-* из routeprofiles release. Полный список Throne (~2174) — через Add URL…. Зеркало скачивания — Cloudflare jsDelivr (testingcf.jsdelivr.net).

Категория	Примеры
CN / GFW	`geoip-cn`, `geosite-gfw`, `geosite-category-anticensorship`, …
Iran / Russia	`geoip-ir`, `geosite-ru-blocked`, …
Ads / private	`geosite-category-ads-all`, `scepter-adblocksingbox`
Сервисы	`geosite-google`, `geosite-telegram`, `geosite-netflix`, …

Каталог: throneproj/routeprofiles (srslist.h + release).

Идентификаторы (как в App Store Connect)

Что	Значение
Display name	Time2VPN / time2vpn
App	`com.time2map.vpn`
Tunnel appex	`com.time2map.vpn.tunnel`
App Group	`group.com.time2map.vpn`
ASC Apple ID	`6792749221`
SKU	`vpnwithtun`
`DEVELOPMENT_TEAM`	пусто — задать в Xcode

Запись приложения в App Store Connect недостаточна. Владелец/админ на developer.apple.com → Certificates, Identifiers & Profiles должен создать:

App ID com.time2map.vpn с Network Extension (Packet Tunnel) + App Groups
App ID com.time2map.vpn.tunnel с Packet Tunnel + App Groups
App Group group.com.time2map.vpn, назначенный обоим App ID

Без appex App ID и группы подпись Network Extension всё равно упадёт. Подробности — в английской секции и в ARCHITECTURE.md.

Только Personal Team в Signing & Capabilities

Personal Team нельзя использовать для Packet Tunnel / Network Extension — нужна оплаченная Program-команда.

Если в Settings → Accounts команда видна (Admin), а в Team dropdown проекта её нет — чаще всего: членство Individual (Admin в App Store Connect ≠ доступ к подписи), нет галочки Access to Certificates, Identifiers & Profiles, или не создан сертификат Apple Development. Пошагово: apps/macos-tunnel/README.md.

Лицензия

GNU GPL v3

Navigation Menu

Repository navigation

About

Repository files navigation

Scepter

Goals

Product intent (for Apple / reviewers)

macOS TUN / Network Extension (hard requirements)

Build status (Phase 1)

Identifiers (App Store Connect / portal)

Portal checklist (owner/admin)

How to set Team ID in Xcode

Troubleshooting: only Personal Team in Signing picker

Desktop deps (Homebrew, arm64)

Build order

Package macOS DMG (Time2VPN)

Layout

Architecture: Swift NE vs Qt UI

Profiles / routing (Swift host — current)

Default remote rule-set URLs (Throne / MetaCubeX)

Relation to Throne

License

Scepter (RU)

Цели

Назначение продукта (для Apple / ревьюеров)

Статус Phase 1

Зависимости desktop (Homebrew, arm64)

Сборка Qt-приложения

DMG для macOS (Time2VPN)

Архитектура: Swift NE vs Qt UI

Дефолтные URL rule-set (как у Throne / MetaCubeX)

Идентификаторы (как в App Store Connect)

Только Personal Team в Signing & Capabilities

Лицензия

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
apps		apps
daemon/core		daemon/core
docs		docs
protocol		protocol
scripts		scripts
third_party		third_party
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
CMakeLists.txt		CMakeLists.txt
LICENSE		LICENSE
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

Scepter

Goals

Product intent (for Apple / reviewers)

macOS TUN / Network Extension (hard requirements)

Build status (Phase 1)

Identifiers (App Store Connect / portal)

Portal checklist (owner/admin)

How to set Team ID in Xcode

Troubleshooting: only Personal Team in Signing picker

Desktop deps (Homebrew, arm64)

Build order

Package macOS DMG (Time2VPN)

Layout

Architecture: Swift NE vs Qt UI

Profiles / routing (Swift host — current)

Default remote rule-set URLs (Throne / MetaCubeX)

Relation to Throne

License

Scepter (RU)

Цели

Назначение продукта (для Apple / ревьюеров)

Статус Phase 1

Зависимости desktop (Homebrew, arm64)

Сборка Qt-приложения

DMG для macOS (Time2VPN)

Архитектура: Swift NE vs Qt UI

Дефолтные URL rule-set (как у Throne / MetaCubeX)

Идентификаторы (как в App Store Connect)

Только Personal Team в Signing & Capabilities

Лицензия

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages