免越狱接管 Apple /clls/wloc 定位流:iOS-Location-Spoofer-Web 的流式 Protobuf 引擎、边缘网关与兼容边界实测

免越狱接管 Apple /clls/wloc 定位流:iOS-Location-Spoofer-Web 的流式 Protobuf 引擎、边缘网关与兼容边界实测

免越狱环境下修改 iOS 设备全局定位,传统路线往往依赖 Mac / Windows 桌面端连接 Xcode DeveloperDiskImage 或 libimobiledevice 调试通道,一旦拔掉数据线或重启设备就会失效。最近我把开源项目 akudamatata/iOS-Location-Spoofer-Web(CC BY-NC-SA 4.0 协议)拉到本地做了一轮完整源码审计与协议实测,发现它用一套极轻量的组合把整条链路搬到了移动端与边缘节点:以 Cloudflare Pages + KV 作为全栈控制台,通过 Shadowrocket 的 HTTPS MITM 拦截 Apple /clls/wloc 二进制定位响应,再用零 BigInt 依赖的纯 JS 流式 Protobuf 引擎执行“最小改写”。

更有意思的是,顺着它的 50 条提交历史与核心代码往下挖,我不仅看到了从“令牌硬注入漏洞”到 HTMLRewriter 脱敏的重构现场,还实测出 iOS 12+ JavaScriptCore 兼容、4+1 封包探测与滑窗兜底的底层细节,以及几处尚未被文档提及的代码层边界与小 Bug。这篇文章把它的全栈架构、二进制改写机理与实战避坑一次拆清。

[!NOTE] 源码审计基线与本机实测说明
本文所有文件路径、协议字段号、阈值常量与安全审计结论,均对照自开源仓库 akudamatata/iOS-Location-Spoofer-Web(审计至 commit 13e59f5,2026-09-02)。核心客户端引擎 location-spoofer.js 共 922 行,边缘服务端由 functions/ 下 7 个 Cloudflare Pages Functions 构成,前端面板 public/index.html 为单文件 1,905 行实现。

我在本地 Node.js 环境对 location-spoofer.js 导出模块的实测结果:

  • 对南半球坐标 -33.86882(放大 10^8 倍为 -3386882000)执行 Varint64.encodeSigned() 与 Varint64.decode() 往返测试,输出 10 字节补码序列 b09081b1f3ffffffff01,无损还原为 -3386882000;
  • 构造包含 1 条 Wi-Fi(Tag 2)、1 条蜂窝基站(Tag 22)及未知根字段 Tag 33 的 110 字节标准 ARPC 封包输入 spoofAppleResponse(),成功识别为 kind: 'arpc',改写 wifiCount: 1、cellCount: 1,并完整透传根字段 [2, 22, 33]。

一、五层全栈拓扑:零服务器运维的边缘控制面 + 本地 MITM 数据面

在传统自建定位方案里,开发者常需要自己维护一台跑 Docker 的 VPS,既要管域名证书、又要担心后端进程挂掉。iOS-Location-Spoofer-Web 在 2026-07-10 彻底删掉了 docker-compose 与环境变量模板,把控制面完全切到了 Cloudflare Pages + KV 的免费边缘额度上,形成了极简的五层栈式结构。

iOS-Location-Spoofer-Web 五层全栈架构与系统边界

把这五层按职责拆开看,每一层的代码密度都非常克制:

层级 核心文件与组件 关键职责与技术选型
L5 · 客户端面板 public/index.html、public/manifest.json 单文件无构建工程(无 React/Webpack),直接引用 Leaflet 1.9.4,实现 Liquid Glass(液态玻璃)UI、PWA 全屏沉浸适配与双坐标系纠偏。
L4 · 边缘接口层 functions/*.js(7 个边缘函数) 借助 Cloudflare HTMLRewriter 注入运行时开关,通过 KV 命名空间 SPOOFER_DATA 读写 loc 与 favorites(上限 100 条)。
L3 · 代理隧道层 public/ios-location-spoofer.sgmodule、functions/ios-location-spoofer.sgmodule.js 动态生成带当前域名与 Token 的 Shadowrocket 模块,利用 %APPEND% 注入 MITM 主机名,开启 binary-body-mode=1 接管二进制响应体。
L2 · 二进制改写核 location-spoofer.js(与 public/location-spoofer.js 完全一致) 零依赖实现 64 位 Varint 编解码、Apple ArpcCodec、4+1 封包探测与 WLOC 最小改写。
L1 · 系统边界层 iOS locationd 与 /clls/wloc 服务 覆盖 iOS 12.0 ~ iOS 26.x 与 iOS 27 beta 1 ~ 5;但 iOS 27 beta 6+ 因苹果开启强 TLS 证书固定(Certificate Pinning),所有 MITM 路线均已失效。

这里有一个很容易被忽略的工程细节:打开 public/ios-location-spoofer.sgmodule,能看到它劫持的域名并不只有苹果官方的 gs-loc.apple.com、gs-loc-cn.apple.com 与 gsp-ssl.ls.apple.com,还同时覆盖了高德定位辅助域 bluedot.is.autonavi.com 及其阿里 DNS 别名 bluedot.is.autonavi.com.gds.alibabadns.com,匹配路径统一锁定为 /clls/wloc(?:\?.*)?$。在国行 iOS 设备开启定位服务时,系统会向国内分发节点发起混合请求,漏掉高德边缘域名就会出现“微信改成功了、系统地图却飘回真实位置”的割裂现象。


二、核心二进制引擎深潜:location-spoofer.js 如何改写 Apple WLOC

整个项目技术含量最高的部分都在 location-spoofer.js(922 行)。在 2026-09-02 的重构(commit 0094ea5)中,作者把早期外部依赖脚本彻底重写为纯原生模块化架构,集中解决了两个底层难题:老旧 JavaScriptCore 的 64 位整型溢出,以及新版本 iOS 对未知 Protobuf 字段的严格校验。

1. 为什么放弃 BigInt,手写双 32 位 Varint64?

Apple WLOC 协议里的经纬度并不是 IEEE-754 浮点数,而是将角度乘以 100,000,000(10^8)后编码为有符号 64 位整数(Varint)。以北京默认坐标 39.90872 为例,乘以 10^8 后为 3,990,872,000——已经超过了 JavaScript 常规位运算(<<、>>、|)的 32 位有符号上限 2,147,483,647。如果直接用普通 JS 位运算编码经纬度,高位比特会被无情截断,结果直接变成错误坐标。

那为什么不直接用 ES2020 的 BigInt?因为 Shadowrocket 的脚本运行在 NEPacketTunnelProvider 网络扩展沙盒内的 JavaScriptCore 中,在 iOS 12 ~ iOS 13 老设备或低版本系统内核下并不支持 BigInt。为此,作者在 Varint64 模块(第 162–255 行)用双 32 位无符号字({ low, high })和二进制补码算术手搓了一套完整的 64 位 Varint 编解码器:

  • 高位拆分:用 Math.floor(num / 4294967296) >>> 0 提取高 32 位,用 num >>> 0 提取低 32 位,安全范围覆盖到 Number.MAX_SAFE_INTEGER(9007199254740991),远超全球经纬度 ±180 × 10^8 的量级;
  • 负数补码:遇到南半球或西半球负坐标(如我实测的 -33.86882)时,fromSigned() 先对绝对值按位取反再加 1,并在 low === 0 时手动向 high 进位(carry),编码出标准的 10 字节 64 位负数 Varint;
  • 跨边界右移:在 encodeWords() 循环中,每次吐出 7 个 payload 比特后,通过 ((low >>> 7) | (high << 25)) >>> 0 把高字最低 7 位无缝拼接到低字顶部,彻底绕开 BigInt 依赖。

2. “4+1” 封包探测与 WLOC 最小改写决策流

Apple /clls/wloc 的 HTTP 响应体并不是裸露的 Protobuf,不同 iOS 版本与请求类型会在外层套上不同格式的二进制信封(Envelope)。我在 extractEnvelope() 与 spoofAppleResponse()(第 594–722 行)梳理出了它的五级递进探测链:

WLOC 4+1 封包探测与最小改写决策流

这五级探测按优先级依次匹配:

  1. Synthetic 封包:校验 responseBytes 前缀是否符合 0x00 0x01 ... 0x00 0x00 特征,并读取第 8–9 字节大端无符号 16 位长度提取负载;
  2. 结构化 ARPC 封包:调用 ArpcCodec.parse() 按大端字节序依次解析 version (u16)、locale / appIdentifier / osVersion(2 字节长度前缀 Pascal 字符串)、functionId (u32) 与 payloadLength (u32);
  3. Marker 签名封包:通过 ByteUtils.findSequence() 全局检索 6 字节特征码 00 00 00 01 00 00,紧随其后读取 u16BE 长度切出负载;
  4. Bare 裸 Protobuf:直接校验首字节 wireType(0 或 2)与 fieldNumber > 0;
  5. 滑窗特征扫描兜底(scanPatchRawBuffer):当苹果微调外层包头导致前 4 路全部失配时,引擎会先以步长 2 扫描前 96 字节偏移,再以步长 1 补扫 0–256 字节区间,尝试把每个偏移切片喂给 patchWlocPayload(),一旦成功改写出至少 1 条 Wi-Fi 或基站记录,立刻用标准 APPLE_SYNTHETIC_PREFIX 重新封包回传。

最核心的工程智慧体现在 patchWlocPayload()(第 516–541 行)的 WLOC 最小改写(Minimal Rewrite) 策略上:

// patchWlocPayload 核心透传逻辑(location-spoofer.js L522-534)
for (var i = 0; i < fields.length; i += 1) {
  var f = fields[i];
  if (f.fieldNumber === 2 && f.wireType === 2) {
    parts.push(ProtobufEngine.makeLengthDelimitedField(2, patchWifiEntity(f.valueBytes, config)));
    wifiCount += 1;
  } else if (CELL_RESPONSE_TAGS[f.fieldNumber] && f.wireType === 2) {
    parts.push(ProtobufEngine.makeLengthDelimitedField(f.fieldNumber, patchCellEntity(f.valueBytes, config)));
    cellCount += 1;
  } else {
    // 关键:其余根级字段(包括 3, 4, 33 等)全量原样透传,不丢弃!
    parts.push(f.raw);
  }
}

早期的很多定位脚本喜欢把响应解码成 JSON 后只挑几个字段重新拼装,结果一旦遇上 iOS 18 ~ 27 新增的根级元数据字段(如源码注释点名的 Tag 3、4、33)就会因为结构残缺被 locationd 直接拒收。这里的 ProtobufEngine.readFields() 在解析每个字段时都保留了原始字节切片 f.raw:

  • 对 Wi-Fi 实体(根 Tag 2 -> 子字段 Tag 2)和蜂窝基站实体(根 Tag 22 / 24 -> 子字段 Tag 5)中的 Location 子消息,仅当确认同时存在字段 1(纬度)与 2(经度)时,才原地替换字段 1、2 与字段 3(水平精度 horizontalAccuracy);
  • 其余 BSSID、信号强度、时间戳以及所有未定义 Protobuf 字段,全部通过 f.raw 一字节不差地原样回写。同时 failOpen 默认开启,哪怕解析抛出异常也会执行 $done({}) 放行原始响应,避免断网或导致定位服务假死。

[!WARNING] 我在源码审计中发现的两处逻辑反差

  1. 海拔与垂直精度其实“存而未改”:前端底部抽屉、functions/set.js 的 KV 存储,乃至 location-spoofer.js 顶部的 CONFIG_DEFAULTS 与 runShadowrocket()(第 873–874 行),都完整同步了 altitude 与 verticalAccuracy。但实际执行二进制改写的 patchLocationRecord()(第 455–486 行)其实 只处理了 fieldNumber 1(纬度)、2(经度)和 3(水平精度),并没有把海拔和垂直精度写入 WLOC Protobuf 报文。换句话说,目前面板上调整这两个高级参数只会存入 KV,并不会实际影响系统返回的模拟海拔。
  2. 静态与透传分支的冗余写法:在 ProtobufEngine.makeVarintField()(第 345–347 行)中,判断 signedOrUnsignedVal < 0 的三元表达式两个分支调用的都是 Varint64.encodeSigned(signedOrUnsignedVal);另外在 spoofAppleResponse() 组装回包时,如果命中 bare(裸 Protobuf),脚本会强制给它套上一层 APPLE_SYNTHETIC_PREFIX(0001000000010000 + 2 字节长度),而不是保持裸 Protobuf 返回,这一点在排查特定系统版本的原始响应回放时需要注意。

三、四域协同生命周期:鉴权修复、坐标纠偏与动态同步

搞定了底层二进制改写,Web 面板如何安全地把坐标传递给手机端的小火箭脚本?项目用 Cloudflare Pages Functions + HTMLRewriter 搭出了一套四域协同链路。

四域协同鉴权、坐标纠偏与动态定位同步泳道图

1. 从“HTML 明文泄密”到 HTMLRewriter 脱敏

翻看 Git 提交历史时,我注意到 2026-09-02 的一次关键安全修复(commit f0af3da):在此之前的版本里,functions/index.js 直接把环境变量 env.TOKEN 原封不动地拼接进 <script>window.__CFG__={ token, amapKey }</script> 塞回给前端页面!这意味着只要有人对站点首页执行一次简单的 curl,就能直接拿到管理员的明文 TOKEN,所谓的“30 天液态玻璃密码锁屏”形同虚设。

修复后的 functions/index.js 改成了严格的布尔标志位注入:

const hasToken = Boolean(env.TOKEN);
const amapKey = env.AMAP_KEY || '';
const configScript = `<script>window.__CFG__=${JSON.stringify({ hasToken, amapKey })};</script>`;

浏览器收到页面后,先检查 HAS_TOKEN。如果服务端开启了鉴权,则校验 localStorage 中有效期 30 天的 gps_session,并通过 GET /verify?token=... 向边缘节点验真,验证通过才把密钥写入本地缓存并开始拉取 /loc.json 与 /favorites。

2. 中国区火星坐标系(GCJ-02)与 WGS-84 的往返闭环

Apple 底层 /clls/wloc 必须接收全球标准的 WGS-84 坐标,但国内用户最习惯使用的高德地图底图和地名检索(restapi.amap.com/v3/assistant/inputtips)全部运行在加密偏转后的 GCJ-02 坐标系下。

public/index.html 内置了一套无外部依赖的 GCJ 转换器(第 1131–1159 行):

  • 当切换到高德地图(amap)或高德卫星(sat)时,内部存储与提交的 WGS 状态始终保持 WGS-84,仅在渲染地图中心点、蓝色已锁定图钉(updateLockedPin)或处理高德搜索结果时实时转换;
  • 当切换到 CartoDB 国际地图(osm)或 Esri 卫星(esri)时,直接透传原始 WGS-84 坐标;
  • 消除浮点往返误差的细节:由于 GCJ.w2g() 与近似反解 GCJ.g2w() 存在微米级往返浮点误差,早期用 6 位小数精确比对会导致“刚收藏的位置再点过去,星标却不亮”。作者在 coordMatch()(第 1551–1554 行)专门设定了 0.000015°(约 1.7 米)的容差窗口,彻底稳住了星标状态高亮与防重复收藏。

3. 一键模块导入与 configUrl 热同步

用户不需要在手机端手动改写任何脚本。点击设置面板的“一键导入模块”时,前端会动态拼装当前域名与 Token,触发 shadowrocket://install/module?url=... 协议唤醒小火箭,请求边缘函数 functions/ios-location-spoofer.sgmodule.js。该边缘函数在响应瞬间把静态模板里的占位符 你的域名 和 你的Token 实时替换为真实 Host 与 Token。

导入后,每次 Apple locationd 发起 /clls/wloc 请求并被 Shadowrocket 拦截时,runShadowrocket() 会带着 5 秒超时向 configUrl(即 https://你的域名/loc.json?token=...)发起 $httpClient.get(),拉取最新锁定的坐标并即时改写返回包。配合 iOS 端“关闭定位服务等待 10 秒再重新开启”清掉系统基站缓存,几秒内就能把新坐标刷进微信、高德或系统地图。


四、部署前必读:代码审计暴露的 4 项细节瑕疵与安全边界

虽然这套架构在个人单用户场景下非常优雅,但把全量代码一行行审计下来,我还是抓出了几个尚未修复的工程瑕疵,如果你打算 Fork 自建,建议顺手补齐:

[!CAUTION] 源码级细节瑕疵与安全建议

  1. 收藏夹跳转到 Esri 国际卫星图层时的 500 米偏移 Bug:在 public/index.html 第 1588 行的收藏夹条目点击事件中,代码写的是 var disp=currentLayer==='osm'?[f.latitude,f.longitude]:GCJ.w2g(f.latitude,f.longitude);——唯独漏掉了同属 WGS-84 坐标系的 'esri'!对照全文件其余四处(onMapMove、switchLayer、doSearch、updateLockedPin)均正确判断了 currentLayer==='osm'||currentLayer==='esri'。结果就是如果你正在用“国际卫星”图层,点开收藏夹跳回中国境内地点时,地图中心会意外偏移几百米。修复只需补全 ||currentLayer==='esri' 即可。
  2. 未配置高德 Key 时的 XSS 风险点:高德搜索分支(第 1397 行)和收藏夹渲染(第 1578 行)都对名称调用了 escHtml() 转义;但当未配置 AMAP_KEY 回退到 OpenStreetMap Nominatim 搜索时,第 1425 行直接把第三方接口返回的 parts[0] 拼进了 row.innerHTML。同样,搜索历史(第 1336 行)把用户输入仅做单引号转义后直接塞进了内联 onclick 属性。建议统一改用 textContent 与 addEventListener。
  3. 高德 Key 仍暴露于未鉴权首页 & Token 经 URL 传递:虽然 env.TOKEN 已经脱敏,但 functions/index.js 依然会把明文 AMAP_KEY 注入未登录也能访问的首页 HTML 中(建议在高德控制台务必为该 Key 配置 HTTP Referer 白名单,限制仅允许自己的 .pages.dev 或自定义域名调用)。此外,全站 API 与 .sgmodule 均采用 ?token= 查询参数鉴权且 authOk() 使用普通 === 比对,Token 会留在浏览器历史与代理配置 URL 中,绝不能复用常用个人密码作为 TOKEN。
  4. iOS 27 beta 6+ 的系统级终局限制:正如仓库兼容性矩阵所标注,一旦设备升级到启用了强制 TLS Certificate Pinning 的系统版本,无论脚本怎么优化 Protobuf 探测,系统定位进程都会直接拒绝 Shadowrocket 签发的本地 CA 证书。对于测试机而言,保留在 iOS 12 ~ iOS 26.x(或 iOS 27 beta 5 及以下)是目前 MITM 路线的硬前提。

综合来看,akudamatata/iOS-Location-Spoofer-Web 把一个原本高度依赖桌面端硬件连线的工具,压缩成了一套零运维成本的 Serverless Web 应用:前端用单文件原生 JS 撑起了流畅的 Liquid Glass PWA 体验与双坐标系纠偏,底层用零 BigInt 的手写 64 位 Varint 与最小改写策略扛住了多年来的协议演进。对于需要频繁做 LBS 跨区联调、测试定位回调边界或研究 Apple 私有定位协议的开发者而言,它既是一套拿来即用的利器,也是一份极佳的轻量级二进制代理工程参考样本。


原文链接与参考资料