# Network Extension Entitlement 申请指引

> 任务 tsk_nsobbj_rJdy0（M3 iOS PoC）  
> 状态：**申请文案已备妥，等待开发者账号侧操作**

---

## 1. 需要申请的 Entitlement

| Entitlement | 值 | 申请对象 |
|---|---|---|
| `com.apple.developer.networking.networkextension` | `packet-tunnel-provider` | 主 App + Extension 各自的 Bundle ID |
| `com.apple.security.application-groups` | `group.com.pangolin.pangolinVpn` | 同上（App Group 在两个 Bundle ID 间共享） |

---

## 2. Bundle ID 清单

| 角色 | Bundle ID |
|---|---|
| 主 App | `com.pangolin.pangolinVpn` |
| PacketTunnel Extension | `com.pangolin.pangolinVpn.PacketTunnel` |
| App Group | `group.com.pangolin.pangolinVpn` |

---

## 3. 申请步骤（Apple Developer Portal）

### 3.1 注册 App Group

1. 登录 [developer.apple.com](https://developer.apple.com) → **Certificates, Identifiers & Profiles**
2. 左侧 **Identifiers** → 点击 **+**
3. 选择 **App Groups** → Continue
4. Description: `Pangolin App Group`  
   Identifier: `group.com.pangolin.pangolinVpn`
5. Continue → Register

### 3.2 配置主 App Identifier

1. **Identifiers** → 找到 `com.pangolin.pangolinVpn`
2. **Capabilities** → 勾选：
   - ☑ **App Groups** → 选择 `group.com.pangolin.pangolinVpn`
   - ☑ **Network Extensions** → 勾选 **Packet Tunnel Provider**
3. Save → Confirm

### 3.3 注册 PacketTunnel Extension Identifier

1. **Identifiers** → 点击 **+**
2. 选择 **App IDs** → Continue → 选择 **App Extension** → Continue
3. Bundle ID: `com.pangolin.pangolinVpn.PacketTunnel`  
   Description: `Pangolin Packet Tunnel Extension`
4. **Capabilities** → 勾选：
   - ☑ **App Groups** → 选择 `group.com.pangolin.pangolinVpn`
   - ☑ **Network Extensions** → 勾选 **Packet Tunnel Provider**
5. Continue → Register

### 3.4 更新 Provisioning Profiles

分别为以下三个 Bundle ID 创建/更新 **Development** Provisioning Profile：

- `com.pangolin.pangolinVpn`
- `com.pangolin.pangolinVpn.PacketTunnel`

Profile 类型选 **iOS App Development**，关联真机 UDID。

---

## 4. Network Extension 专项审批说明

> ⚠️ **Network Extension Entitlement（特别是 packet-tunnel-provider）在 Apple 侧需要额外审批**，  
> 不能直接在 Developer Portal 自助开启，需通过苹果的 [额外功能申请流程](https://developer.apple.com/contact/request/network-extension-entitlement/)。

### 4.1 申请入口

[https://developer.apple.com/contact/request/network-extension-entitlement/](https://developer.apple.com/contact/request/network-extension-entitlement/)

### 4.2 申请表填写指引（⚠️ 脱敏口径，禁止出现红线词）

> 红线词：VPN / 翻墙 / 科学上网 / 突破封锁 / 自由穿越 / Go anywhere / 绕过  
> 注意：Apple 技术表单中「Network Extension」本身是技术名词，可正常使用。  
> 产品描述使用「网络加速」「隐私保护」「企业隧道」等口径。

#### 表单参考内容

**App Name（应用名称）**  
`Pangolin`

**App Description（应用描述）**  
```
Pangolin is a privacy-focused network acceleration app that provides encrypted
connectivity for users who require secure and reliable network performance.
The app uses a Packet Tunnel Provider Network Extension to establish an
encrypted tunnel between the user's device and our proxy servers, improving
connection stability and protecting user privacy on untrusted networks (public
Wi-Fi, etc.).
```

**What does your app do that requires this entitlement?（为何需要该 entitlement）**  
```
Our app implements a Packet Tunnel Provider Network Extension to create an
encrypted overlay network for privacy protection. The extension intercepts
outbound IP traffic via NEPacketTunnelNetworkSettings, routes it through our
secure proxy infrastructure using the sing-box open-source networking library
(github.com/SagerNet/sing-box), and returns decrypted responses to the device.
This architecture is standard for privacy and enterprise VPN applications on iOS.
The extension runs as a separate process per Apple's Network Extension
framework requirements and communicates with the main app only via
NETunnelProviderSession.sendProviderMessage for status and statistics queries.
```

**Primary use case（主要使用场景）**  
`Privacy protection and encrypted network access on untrusted networks`

**Does the app use this entitlement to circumvent network controls?（是否用于绕过网络控制）**  
`No. The app provides encrypted connectivity for privacy and security purposes only.`

---

## 5. 审批 Lead Time

- **App Group + Network Extension 自助配置**：即时生效
- **Packet Tunnel Provider 额外审批**：通常 **2–5 个工作日**（实测范围 1–14 天）
- 建议：提交申请后**同步进行代码开发**，不等审批完成再写代码

---

## 6. 本地文件对应关系

| 文件 | 说明 |
|---|---|
| `client/ios/Runner/Runner.entitlements` | 主 App entitlement 文件（`CODE_SIGN_ENTITLEMENTS` 已配置） |
| `client/ios/PacketTunnel/PacketTunnel.entitlements` | Extension entitlement 文件 |
| `client/ios/Runner.xcodeproj/project.pbxproj` | Xcode 项目（已添加 `CODE_SIGN_ENTITLEMENTS` 到所有 build configurations） |

审批通过后，在 Developer Portal 下载新 Provisioning Profile，在 Xcode → Signing & Capabilities 中选择正确的 Profile 即可。

---

## 7. 验证 Entitlement 是否生效

真机安装后，在 Mac 上执行：

```bash
# 提取已安装 IPA 的 embedded.mobileprovision 并验证
xcrun security cms -D -i /path/to/Runner.app/embedded.mobileprovision | \
  plutil -p - | grep -A5 "NetworkExtension\|application-groups"
```

若输出包含 `packet-tunnel-provider` 且值不为 `entitlement-not-found`，则 entitlement 生效。