OpenHRTT WLoc

OpenHRTT WLoc 是一款完全开源、使用 Swift 编写的实验性工具，专为 iOS 和 macOS 开发者及高级用户设计。它允许用户在地图上搜索或选择任意坐标，并通过 Packet Tunnel 结合本地 HTTPS 代理技术，在设备内部拦截并修改 Apple 定位服务的响应数据，从而实现高精度的位置模拟。

与传统的系统级越狱插件或需要电脑连接的工具不同，WLoc 采用“中间人”（MITM）架构，仅针对特定的 Apple 定位服务域名进行流量劫持和数据处理，确保了操作的灵活性与相对的安全性。

核心工作原理

1. Packet Tunnel Extension：利用 iOS/macOS 的 Network Extensions 框架建立虚拟专用网络通道。
2. 定向 HTTPS 代理：在隧道内运行一个轻量级代理，只匹配并拦截发往 Apple 定位服务域名的请求。
3. 本地数据处理：在设备内部实时修改定位响应数据包，将真实坐标替换为用户设定的目标坐标。
4. 证书信任链：通过自签名的根证书实现 HTTPS 流量的解密与重加密，确保通信链路在本地闭环。

主要功能特性

• 🗺️ 交互式地图操作：支持地图搜索、点选坐标、收藏夹管理以及快速恢复常用位置。
• 🔄 多坐标系转换：内置 WGS84、GCJ-02（火星坐标）、BD-09（百度坐标）与 Apple Map 坐标之间的相互转换算法，适配不同地图源的需求。
• 🔗 外部链接导入：支持 wlocapp:// URL Scheme，方便从其他应用或快捷指令直接导入坐标。
• 🛡️ 本机证书服务：提供根证书下载与安装引导，确保证书信任链的完整建立。
• 💻 双平台支持：同时提供 iOS 和 macOS 应用目标，满足移动开发与桌面测试的不同场景。

环境要求与前置条件

• 开发环境：macOS 系统，Xcode 16 或更高版本（已在 Xcode 26.6 下验证）。
• 依赖管理：CocoaPods 1.16 或更高版本。
• 加密库：OpenSSL 3.x。
• 开发者账号：必须拥有具备 Network Extensions 能力的 Apple Developer 账号。
• 硬件要求：强烈建议使用真机运行，以完整验证证书信任、VPN 连接及系统定位行为。（模拟器无法完全模拟 Packet Tunnel 行为）。

快速开始指南

1. 获取代码与安装依赖

git clone https://github.com/OpenHRTT/wloc.git
cd wloc
pod install

注意：后续请始终打开 WLocApp.xcworkspace，不要直接打开 .xcodeproj。

2. 生成本地根证书

由于安全原因，仓库不包含任何私钥。你需要在本机生成独立的证书：

chmod +x generate_apple_wloc_p12.sh
./generate_apple_wloc_p12.sh

• 脚本会自动生成 .p12 证书并同步到 App/Extension 资源目录。
• 默认密码为 app-wloc，若修改需同步更新 AppWLocConfig.proxyIdentityPassword。
• 警告：生成的证书文件已被 .gitignore 排除，切勿强制提交到 Git 仓库。

3. 配置签名与唯一标识

在 Xcode 中打开工作空间，对以下四个 Target 进行配置：

• WLocApp-iOS / WLocTunnel-iOS
• WLocApp-macOS / WLocTunnel-macOS

关键步骤：

1. 选择你的开发团队（Team）。
2. 修改 Bundle Identifier，确保 Tunnel 的标识为应用标识加 .tunnel（例如：com.example.wloc 和 com.example.wloc.tunnel）。
3. 统一替换 App Group 标识符 group.com.wlocapp.shared 为你的唯一 ID（涉及 .entitlements 文件和 AppWLocConfig.swift）。
4. 在 “Signing & Capabilities” 中确认已启用 App Groups 和 Network Extensions。

4. 构建与运行

选择 WLocApp-iOS 或 WLocApp-macOS Scheme，连接真机并点击 Run。

使用说明

📱 iOS 端

1. 打开 App，进入“教程”页点击“下载证书”。
2. 在 Safari 中下载并前往 设置 > 通用 > VPN 与设备管理 安装根证书。
3. 前往 设置 > 通用 > 关于本机 > 证书信任设置，手动开启对该根证书的完全信任。
4. 回到 App 地图页，搜索或点选目标位置，点击“锁定位置”。
5. 允许系统添加 VPN 配置，并按提示刷新系统定位服务。
6. 退出 App 时，工具会尝试断开 VPN 并清除锁定状态。

💻 macOS 端

1. 在 App 教程中下载根证书。
2. 将证书导入 “钥匙串访问”，并在测试期间将其信任设置为“始终信任”。
3. 在地图中选择位置并点击“锁定位置”，允许系统创建 VPN/Network Extension 配置。
4. 测试完成后，记得断开 VPN 并删除根证书以恢复系统正常状态。