# iOS VPN Setup Checklist (Personal Use)

Этот чеклист закрывает именно 3 пункта:

1. Добавить и настроить `PacketTunnel` target в Xcode.
2. Настроить `Bundle ID`, `App Group`, `Signing`, `Network Extension`.
3. Подключить `Libbox.xcframework` и установить pod-зависимости.

---

## 0) Перед началом

- Работай на macOS с установленным Xcode.
- Открой проект: `ios/Runner.xcworkspace` (не `Runner.xcodeproj`).
- Убедись, что у тебя есть Apple Developer Team (желательно paid account).

---

## 1) Добавить PacketTunnel target в Xcode

### 1.1 Создание target

1. В Xcode открой `Runner.xcworkspace`.
2. В левом навигаторе выбери синий проект `Runner`.
3. В разделе `TARGETS` нажми `+`.
4. Выбери шаблон: `Network Extension` -> `Packet Tunnel Provider`.
5. Name: `PacketTunnel`.
6. Language: `Swift`.
7. Нажми `Finish`.
8. Если Xcode спросит `Activate scheme?` -> `Activate`.

### 1.2 Привязка существующих файлов из репозитория

В проекте уже подготовлены файлы:

- `ios/PacketTunnel/PacketTunnelProvider.swift`
- `ios/PacketTunnel/Info.plist`
- `ios/PacketTunnel/PacketTunnel.entitlements`

Сделай так:

1. Если Xcode создал свои дефолтные файлы в PacketTunnel target, удали их из target (можно `Remove Reference`).
2. Перетащи в Xcode папку `ios/PacketTunnel/` из Finder.
3. В диалоге добавления включи:
   - `Copy items if needed`: **off** (файлы уже в репо),
   - `Add to targets`: **PacketTunnel**.
4. Проверь `Target Membership` у `PacketTunnelProvider.swift` -> только `PacketTunnel`.

### 1.3 Embed extension в Runner

1. Выбери target `Runner` -> `General`.
2. Найди секцию `Frameworks, Libraries, and Embedded Content`.
3. Убедись, что `PacketTunnel.appex` добавлен как `Embed & Sign`.

Если не добавлен:

1. `Runner` -> `Build Phases`.
2. В `Embed App Extensions` нажми `+`.
3. Добавь `PacketTunnel.appex`.

---

## 2) Настроить IDs, Signing, App Group, Capabilities

> Важно: `Runner` и `PacketTunnel` должны быть на одной Team и с совместимыми entitlement.

### 2.1 Bundle Identifier

Рекомендуемый формат:

- Runner: `com.yourname.vpn`
- PacketTunnel: `com.yourname.vpn.PacketTunnel`

Шаги:

1. `Runner` target -> `Signing & Capabilities` -> выставь `Bundle Identifier`.
2. `PacketTunnel` target -> `Signing & Capabilities` -> выставь `Bundle Identifier`.

### 2.2 Team и подпись

Для обоих target (`Runner`, `PacketTunnel`):

1. `Automatically manage signing` -> ON.
2. `Team` -> одна и та же команда.
3. `Signing Certificate`/`Provisioning Profile` должны подтянуться автоматически.

### 2.3 App Group

Для обоих target добавь capability `App Groups` и **одинаковую** группу:

- `group.com.yourname.vpn`

Шаги:

1. `Signing & Capabilities` -> `+ Capability` -> `App Groups`.
2. Создай/выбери группу `group.com.yourname.vpn`.
3. Повтори для второго target.

### 2.4 Network Extension capability

Для обоих target:

1. `+ Capability` -> `Network Extensions`.
2. Тип: `Packet Tunnel`.

### 2.5 Синхронизация build settings (если Xcode не подставил)

Проверь:

- `Runner` использует `ios/Runner/Runner.entitlements`
- `PacketTunnel` использует `ios/PacketTunnel/PacketTunnel.entitlements`
- `PacketTunnel` использует `ios/PacketTunnel/Info.plist`

Где смотреть:

1. Target -> `Build Settings`.
2. Найти `Code Signing Entitlements`.
3. Найти `Info.plist File`.

### 2.6 Значение App Group в plist/entitlements

В проекте уже задано через `AppGroupIdentifier` и переменные.
Если будут ошибки по group id, можно временно зафиксировать вручную:

- в `Runner.entitlements` и `PacketTunnel.entitlements` поставить literal `group.com.yourname.vpn`.

---

## 3) Подключить Libbox.xcframework + pods

### 3.1 Положить framework

Нужный путь:

- `ios/Frameworks/Libbox.xcframework`

Проверь, что папка действительно называется **ровно** `Libbox.xcframework`.

### 3.2 Установить pods

Из корня проекта:

```bash
flutter pub get
cd ios
pod install
```

Если `pod install` ругается на framework:

- проверь путь `ios/Frameworks/Libbox.xcframework`;
- удали кэши и повтори:

```bash
cd ios
pod deintegrate
pod install
```

### 3.3 Открывать только workspace

После pod install всегда открывай:

- `ios/Runner.xcworkspace`

---

## 4) Первый запуск на iPhone

1. Подключи iPhone кабелем.
2. В Xcode выбери устройство как run destination.
3. Собери `Runner` scheme (`Cmd + R`).
4. На iPhone подтверди доверие developer certificate (если нужно).
5. Дай разрешение на VPN при первом подключении.

---

## 5) Быстрый preflight перед каждым запуском

- `Runner` и `PacketTunnel` в одной Team.
- `Bundle ID` уникальны и корректны.
- Оба target имеют `App Groups` и `Network Extensions`.
- В `Embed App Extensions` присутствует `PacketTunnel.appex`.
- На месте `ios/Frameworks/Libbox.xcframework`.
- Проект открыт как `Runner.xcworkspace`.

---

## 6) Частые ошибки и фиксы

### `Missing entitlement` / `permission denied`

- Не совпали capabilities между target.
- Неверный provisioning profile.
- App Group не добавлен в оба target.

### `PacketTunnel.appex missing` или не стартует extension

- Не встроен extension в `Runner` (`Embed App Extensions`).
- Неверный bundle id extension.

### `No such module Libbox`

- Нет `Libbox.xcframework` в `ios/Frameworks/`.
- Не выполнен `pod install`.
- Открыт `xcodeproj`, а не `xcworkspace`.

### VPN включается, но трафик не идет

- Неверный конфиг/ссылка.
- Проблемы DNS/route в extension.
- Смотри логи Xcode для `PacketTunnelProvider`.

---

## 7) Что уже подготовлено в этом репозитории

Уже добавлено:

- `ios/Podfile`
- `ios/Runner/Runner.entitlements`
- `ios/PacketTunnel/Info.plist`
- `ios/PacketTunnel/PacketTunnel.entitlements`
- `ios/PacketTunnel/PacketTunnelProvider.swift`
- `ios/Frameworks/README.md`
- iOS deployment target поднят до 15.0 в `ios/Runner.xcodeproj/project.pbxproj`

Тебе осталось довести Xcode-конфиг и положить `Libbox.xcframework`.