wloc 딥다이브
— 탈옥·PC 없이 Apple 네트워크 위치를 바꿔치기하는 프록시 스푸퍼

1프로젝트 한 줄 요약

wloc는 Apple의 네트워크 위치 서비스(WLOC)가 반환하는 좌표를 iOS 프록시 앱의 MITM·스크립트로 가로채, protobuf 응답 안의 위경도를 실시간으로 바꾸는 "탈옥·PC 불필요"의 순수 프록시 방식 가상 위치 도구다. 사용자는 웹 지도에서 원하는 지점을 클릭하고 "기기에 저장"만 누르면, 그 뒤로 아이폰이 네트워크로 위치를 조회할 때마다 조작된 좌표를 진짜 위치로 믿게 된다.

여기서 반드시 구분할 것 하나. wloc는 GPS 신호를 조작하는 게 아니라, Apple 서버가 돌려주는 "답"을 바꾼다. 아이폰의 위치는 GPS 위성 + WiFi/기지국 네트워크 측위 + 블루투스 비콘 등을 종합해 결정되는데, wloc는 그중 네트워크 측위(WLOC) 경로 하나만 건드린다. 그래서 GPS 신호가 강한 야외에서는 덜 먹히고, WiFi 측위에 의존하는 실내에서 가장 잘 통한다(§2·§7에서 상세).

2왜 지금 주목받는가

iOS 위치 스푸핑은 새로운 주제가 아니다. 그런데 wloc가 이번 주 Weekly 18위(★ 4.3k, fork 807)까지 치고 올라온 건 기존 방법들의 고질적 불편을 정면으로 없앴기 때문이다. (TrendShift의 굵은 숫자는 별 수가 아니라 사회적 언급 모멘텀이다.) 먼저 기존 방법들이 왜 아팠는지부터 보자.

주목 포인트 1 — "이미 깔려 있는 프록시 앱"만으로 끝난다

중화권 iOS 사용자 다수는 이미 Surge·Quantumult X·Loon·Shadowrocket 같은 유료 프록시 앱을 쓴다. wloc는 별도 앱을 설치하라고 하지 않는다. 대신 그 프록시 앱들이 원래 제공하는 MITM + JavaScript 스크립트 기능에 설정 파일 하나만 얹으면 된다. "새 도구를 배우는 비용"이 거의 0에 가깝다.

주목 포인트 2 — GPS가 아니라 "네트워크 위치"를 노리는 영리함

대부분의 스푸핑 도구가 GPS 하드웨어를 흉내내려 애쓸 때, wloc는 관점을 뒤집었다. "아이폰이 Apple에 위치를 물어보는 그 요청/응답을 가로채면, 하드웨어를 건드리지 않고도 답을 바꿀 수 있다"는 것. 프록시는 어차피 모든 트래픽을 거치므로, 위치 조회 트래픽(/clls/wloc) 한 줄만 골라내 응답을 리라이트하면 그만이다. 발상 자체가 학습 가치가 높다.

주목 포인트 3 — "점 찍기" UX와 iOS 단축어 연동

위경도를 손으로 입력할 필요가 없다. Leaflet 지도 웹페이지에서 클릭·지명 검색·지도 링크 붙여넣기로 지점을 고르고 버튼 한 번이면 저장된다. 더 나아가 iOS 단축어(Shortcuts)를 등록하면 Apple 지도·高德(가오더) 지도의 공유 시트에서 바로 "이 위치로 전환"이 가능하다. "기술"이 아니라 "제품"처럼 다듬은 UX가 일반 사용자를 끌어들였다.

주목 포인트 4 — 서버가 "무상태·무로그"라 셀프호스팅이 쉽다

좌표 선택 페이지와 지도 링크 파싱을 담당하는 서버는 Cloudflare Worker/Pages 위에서 돌고, 사용자 좌표를 저장·로깅하지 않는다. 공용 인스턴스(wloc-pages.pages.dev)를 그냥 써도 되고, 프라이버시가 걱정되면 Cloudflare 무료 티어로 직접 배포하면 된다. "믿고 쓸 수 있는 구조"를 코드로 증명한 셈이다.

3기술 스택 전체 지도

wloc의 스택은 세 개의 세계가 맞물려 있다. ① 프록시 앱 안에서 도는 클라이언트 스크립트(실제 리라이트를 하는 본체), ② 좌표를 고르고 지도 링크를 해석해주는 서버(선택적), ③ 이 둘이 상대하는 Apple의 위치 프로토콜. 하나씩 지도를 그려보자.

(A) 클라이언트 계층 — 6개 프록시 엔진 위에서 도는 JavaScript

같은 번들 스크립트 하나가 런타임을 자동 감지해 6개 프록시 엔진에서 동작한다. dist/wloc.js 최상단이 어떤 앱 안에서 실행 중인지 전역 객체로 판별한다.

// dist/wloc.js — 어떤 프록시 앱 안에서 도는지 런타임 감지
const env = (() => {
  const has = k => k in globalThis;
  switch (true) {
    case has("$task"):   return "Quantumult X";   // QX 전용 전역
    case has("$loon"):   return "Loon";
    case has("$rocket"): return "Shadowrocket";
    case has("Egern"):   return "Egern";
    case Boolean(globalThis.$environment?.["surge-version"]): return "Surge";
    case Boolean(globalThis.$environment?.["stash-version"]): return "Stash";
    case has("Cloudflare"): return "Worker";
    case Boolean(globalThis.process?.versions?.node): return "Node.js";
  }
})();

엔진별로 API가 제각각이라, wloc는 NSNanoCat/Util이라는 크로스플랫폼 추상화 프레임워크를 번들해 Console(로그)·Storage(영구 저장소 래핑)·$done(응답 반환)을 한 겹으로 통일한다. "여러 플랫폼을 하나의 코드로"의 어댑터 패턴이다.

(B) 서버 계층 — Cloudflare Worker/Pages (선택적)

(C) 상대 계층 — Apple WLOC 프로토콜 (Protocol Buffers)

4아키텍처 심화 분석

4-A. 후킹 규칙은 항상 두 개

모듈은 프록시에 규칙을 두 개 건다. 하나는 응답을 가로채는 것, 다른 하나는 요청을 가로채는 것이다.

4-B. 전체 데이터 흐름 — 설정 단계와 발동 단계

4-C. Apple WLOC protobuf 구조 (코드에서 역공학된 필드 맵)

wloc의 파서가 드러내는 실제 스키마는 다음과 같다. protobuf는 각 필드를 tag = (field번호 << 3) | wire타입으로 표시하는데, wloc는 이 규칙으로 바이트를 훑어 "좌표처럼 생긴 레코드"만 골라 값을 갈아끼운다.

핵심 패치 함수(가독화). "좌표 레코드가 맞는지" 먼저 확인하고, 맞을 때만 값을 바꾼 뒤 나머지 필드는 원본 그대로 재직렬화한다 — 모르는 필드를 함부로 버리지 않는 게 포인트다.

// 위치 레코드 리라이트 — lat/lon 둘 다 있을 때만 패치
function patchLocation(buf, target, stat) {
  const fields = readFields(buf);        // protobuf → 필드 배열
  let hasLat = false, hasLon = false;
  for (const f of fields) {
    if (f.fieldNo === 1 && f.wireType === 0) hasLat = true;   // latitude 존재?
    if (f.fieldNo === 2 && f.wireType === 0) hasLon = true;   // longitude 존재?
  }
  if (!hasLat || !hasLon) return buf;    // 좌표 레코드 아니면 그대로 통과

  const out = [];
  for (const f of fields) {
    if      (f.fieldNo === 1 && f.wireType === 0) out.push(enc(1, 0, Math.round(1e8 * target.latitude)));
    else if (f.fieldNo === 2 && f.wireType === 0) out.push(enc(2, 0, Math.round(1e8 * target.longitude)));
    else if (f.fieldNo === 3 && f.wireType === 0) out.push(enc(3, 0, target.accuracy));
    else out.push(f.raw);                // 모르는 필드는 원본 유지
  }
  stat.locations++;
  return serialize(out);
}

Apple 프레임을 벗겨내고 다시 싸는 부분. 2바이트 big-endian 길이 프리픽스가 이 프레이밍의 특징이다.

// [헤더 8B][길이 2B BE][protobuf payload][꼬리] 를 벗겨 패치 후 재조립
function unwrapFrame(buf, base, target, stat) {
  if (buf.length < base + 10) throw new Error("body too short");
  const len = (255 & buf[base+8]) << 8 | (255 & buf[base+9]);   // 2바이트 BE 길이
  if (len <= 0 || len + base + 10 > buf.length) throw new Error("invalid frame length");

  const head    = buf.slice(0, base + 8);            // 헤더
  const payload = buf.slice(base+10, base+10+len);   // protobuf 본문
  const tail    = buf.slice(base+10+len);            // 꼬리

  const patched = patchTopLevel(payload, target, stat);
  if (patched.length > 65535) throw new Error("payload too large");
  return serialize([head, [patched.length >> 8 & 255, 255 & patched.length], patched, tail]);
}

protobuf varint 리더. 7비트씩 쌓고 최상위 비트가 "다음 바이트가 이어짐"을 뜻하는 표준 인코딩이다.

// readVarint → [값, 다음 오프셋]
function readVarint(buf, i) {
  let val = 0, mul = 1, bits = 0;
  while (i < buf.length) {
    const b = 255 & buf[i++];
    if (bits < 56) val += (127 & b) * mul;     // 하위 7비트 누적
    if (!(128 & b)) return [val, i];           // 최상위 비트 0 = 끝
    mul *= 128;
    if ((bits += 7) >= 70) throw new Error("varint too long");
  }
  throw new Error("truncated varint");
}

4-D. 透传(Passthrough) — 진짜 위치로 되돌리는 스위치

설정이 비었거나 좌표가 기본값(sentinel)이면, 응답을 건드리지 않고 그대로 통과시켜 진짜 위치를 복원한다. 기본값은 경도 113.94114, 위도 22.544577(중국 선전 바오안) — 이 좌표가 곧 "미설정" 신호다.

// 저장값이 비었고 모듈 인자가 기본값이면 → 좌표를 null로 만들어 passthrough
if (cfg.longitude === 113.94114 && cfg.latitude === 22.544577) {
  cfg.longitude = null; cfg.latitude = null;
  log.info("[settings] 透传 모드: 저장값 없음 + 기본 인자 → 위치 수정 안 함");
}
// 응답 패치 직전: 좌표가 null이면 원본 응답 그대로 반환
if (cfg.longitude == null || cfg.latitude == null) {
  log.info("[wloc] 透传 모드: 좌표 미설정 → 실제 위치 복원");
  return originalResponse;
}

4-E. 좌표계 변환 — 중국 지도(GCJ-02)를 WGS-84로

중국은 규제상 지도 좌표에 의도적 오차를 넣은 GCJ-02(속칭 火星坐标, "화성 좌표")를 쓴다. 高德·중국 Apple 지도에서 뽑은 좌표를 그대로 주입하면 실제 위치가 수백 미터 어긋난다. 그래서 서버가 GCJ-02 → WGS-84 역변환을 한다. 변환식에 닫힌 역함수가 없어, 불동점 반복(fixed-point iteration)으로 근사한다.

// worker/src/parse.js — GCJ-02 → WGS-84 (반복 역산으로 수렴)
function gcj02ToWgs84(lat, lon) {
  if (outOfChina(lon, lat)) return { lat, lon };   // 중국 밖이면 변환 불필요
  let wLat = lat, wLon = lon;
  for (let i = 0; i < 6; i++) {                    // 6회면 오차 < 0.1m로 수렴
    const g = wgs84ToGcj02(wLat, wLon);            // 정방향 변환은 공식이 있음
    const errLat = g.lat - lat, errLon = g.lon - lon;
    if (Math.abs(errLat) < 1e-9 && Math.abs(errLon) < 1e-9) break;
    wLat -= errLat; wLon -= errLon;                // 오차만큼 되밀기
  }
  return { lat: wLat, lon: wLon };
}

지도 링크에서 좌표를 뽑는 부분도 흥미롭다. Apple 링크는 URL 쿼리(coordinate=/ll=/sll=)에 좌표가 있지만, 高德 단축링크는 302 리다이렉트의 Location 헤더에만 좌표가 담겨 있어 redirect:"manual"로 최대 5회까지 따라가며 추출한다.

5디렉토리 구조 해부

구조가 프로젝트의 정체성을 요약한다. 실제로 "위치를 바꾸는" 두뇌는 dist/의 스크립트 2개이고, modules/는 그 두뇌를 각 프록시 앱에 꽂는 어댑터, worker/는 "어디로 옮길지 고르는" 편의 UI다. 두뇌만 있으면 서버 없이도 동작하지만(모듈 인자로 좌표 직접 입력), 서버가 있으면 "지도에서 점 찍기"라는 사용성을 얻는다 — 기능과 사용성이 깔끔하게 분리돼 있다.

6학습 포인트

wloc는 코드량이 크지 않지만(핵심 소스 약 1,500줄), 다루는 개념의 밀도가 높다. 아래는 제품을 쓰지 않아도 개발자에게 남는 지식이다.

① HTTPS MITM 인터셉션의 실전

왜 "인증서를 신뢰"시키면 암호화된 HTTPS를 들여다볼 수 있는지, 왜 특정 호스트만 골라(gs-loc.apple.com) 복호화하는지. TLS 신뢰 사슬과 중간자의 원리를 손으로 만지며 이해한다. 보안 학습의 정석 주제.

② 프록시 리라이트 스크립팅 API 비교

Surge·QX·Loon·Stash가 같은 일을 얼마나 다른 문법으로 하는지(http-response vs script-response-body vs YAML script), binary-body-mode·$persistentStore·$done 같은 공통 개념, 그리고 이걸 하나의 코드로 추상화하는 어댑터 패턴(NSNanoCat/Util).

③ Protobuf 역공학 — 스키마 없이 바이트 읽기

.proto 파일 없이 바이트만 보고 wire type(0=varint, 2=length-delimited …)과 필드 번호를 파싱하는 법, tag = (field << 3) | wireType 규칙, varint 인코딩, 그리고 아는 필드만 골라 바꾸고 모르는 필드는 보존하는 부분 패치 기법. 바이너리 프로토콜 리버싱의 축소판이다.

④ 제약된 런타임에서의 self-contained 구현

zlib 없이 순수 JavaScript gzip inflate, Buffer 없이 바이트 배열 조작, 스키마가 흔들려도 안 깨지게 하는 브루트포스 + 폴백 방어 파싱. "라이브러리가 없을 때 바닥부터 짜는" 근육을 기른다.

⑤ iOS 네트워크 측위의 내부

GPS ≠ 네트워크 위치라는 사실, WLOC이 WiFi MAC + 셀 타워를 Apple에 보내 좌표를 받는 구조, locationd 캐시(§7). "아이폰은 어떻게 실내에서도 위치를 아는가?"의 답을 배운다.

⑥ 좌표계(datum)의 함정과 수치 해법

WGS-84 vs 중국 GCJ-02 오프셋, outOfChina 판정, 그리고 닫힌 역함수가 없을 때 불동점 반복으로 역변환을 근사하는 수치기법. 지리 데이터를 다루는 누구나 한 번은 부딪히는 함정이다.

⑦ 서버리스 엣지 — 무상태·무로그 설계

Hono + Cloudflare Workers/Pages로 초경량 API를 짜고, redirect:"manual"로 단축링크 302를 추적하며, 사용자 데이터를 저장하지 않는 프라이버시 우선 서버를 만드는 법.

7시스템 요구사항

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크