archive/location-spoofer

Fork 0

mirror of https://github.com/xweiba/location-spoofer.git synced 2026-09-21 22:30:46 +08:00

Files

T

xweiba 7cf38363cf docs: add community acknowledgements

2026-08-09 16:00:37 +08:00

17 KiB

Raw Blame History

📍 Location Spoofer

iOS Location Service Research & Testing Framework

An open-source project for iOS location-service research, software development testing, and QA validation.

The project uses either an on-device proxy or a third-party proxy client to simulate selected Apple location-service responses in a controlled test environment.

Features · How It Works · Quick Start · Build · 中文

Important

Use this project only for education, research, testing on devices you own, software development, and QA validation.

Use it only on devices, networks, and software environments that you own or are authorized to test. Follow applicable laws, network policies, and service terms.

The project does not guarantee compatibility with every iOS version or third-party app, and it does not promise to bypass third-party security controls, business restrictions, or service rules.

Project Scope

Location Spoofer is a tool for studying iOS location-service behavior and testing location-dependent software.

It provides:

Native map selection and location-scenario switching;
Controlled simulation of selected Apple location-service responses;
App Mode and Third-party Proxy Mode;
Map coordinate detection with paired WGS-84 and GCJ-02 values;
Environment checks, runtime logs, and diagnostics;
Favorite locations and restoration of the previous map state.

The project does not modify the target app's source code and does not provide telemetry, remote control, or data collection services.

Feature Overview

Native map interaction
- Uses MapKit for the map and system blue dot;
- Supports search, map taps, center-point dragging, and zooming;
- Supports favorites and restoration of the latest selection;
- Shows both domestic and international coordinate representations with separate copy actions.
Location-service response simulation
- Processes only the Apple location-service requests defined by the project;
- Returns the selected coordinates in a controlled test environment;
- Does not require changes to the target app.
Two runtime modes
- App Mode: runs the Go proxy on-device and covers only the current Wi-Fi network;
- Third-party Proxy Mode: uses a supported proxy client and may cover Wi-Fi, 4G, or 5G depending on that client.
Environment checks
- App Mode checks the local proxy, CA trust, and request path;
- Third-party Proxy Mode checks the WLOC configuration API and module response;
- Failures route to the relevant setup or diagnostics screen.
Development diagnostics
- Runtime logs;
- Log copy and cleanup;
- Map coordinate-system change records;
- Sanitized issue-report generation.

How It Works

App Mode

App Mode runs the local Go proxy inside the app. A manual HTTP proxy on the current Wi-Fi routes the selected requests through that on-device proxy.

iOS location request
      │
      │ Manual HTTP proxy on the current Wi-Fi
      ▼
On-device wloccore Go proxy
      │
      │ Handle selected Apple location-service requests
      ▼
Apple location-service response
      │
      │ Test coordinate response
      ▼
The system and apps read the location result

App Mode:

Does not create a Network Extension;
Does not display or occupy the system VPN slot;
Covers only the current Wi-Fi network;
Requires a manual HTTP proxy on that Wi-Fi network;
Requires installation and trust of the CA generated by the app;
Handles only the Apple location-service and environment-verification traffic defined by the project. It is not a general-purpose packet capture tool.

Third-party Proxy Mode

Third-party Proxy Mode does not start the app's Go proxy and does not use the CA generated by the app.

Map selection
  │
  │ WGS-84 coordinates
  ▼
WLOC configuration API
  │
  ▼
Third-party proxy client stores the configuration
  │
  ▼
Third-party client processes location-service requests

In this mode:

The app owns map selection, favorites, coordinate synchronization, and coordinate clearing;
The third-party client owns proxy/VPN, MITM, certificates, and rule execution;
The third-party client owns coordinate persistence;
Wi-Fi, 4G, and 5G support depends on the client;
The configuration may remain active after Location Spoofer closes.

Configuration API and Client Integration

The app does not upload coordinates to a project server. It sends the following GET request, which the third-party client must intercept locally on the device:

https://gs-loc.apple.com/wloc-settings/save

Action	Query parameters	Purpose
Query	`action=query`	Verify module connectivity and read the stored coordinate
Save	`lon=<WGS-84 longitude>&lat=<WGS-84 latitude>&acc=<accuracy>`	Store the selected coordinate
Clear	`action=clear`	Remove the stored test coordinate

The interception script must return HTTP 200 with JSON:

{
  "success": true,
  "longitude": 113.0,
  "latitude": 22.0,
  "accuracy": 25
}

Failures use:

{
  "success": false,
  "error": "Error description"
}

When no coordinate is stored, a query may return {"success":false,"error":"无已保存的坐标"}. The app interprets that response as “module connected, virtual location inactive.” A successful save response must echo the requested WGS-84 longitude and latitude.

To integrate another third-party client:

Add an HTTP request script for gs-loc.apple.com/wloc-settings/save that parses the parameters and returns the specified JSON;
Store coordinates, accuracy, and optional state in the client's persistent storage;
Enable HTTPS decryption for gs-loc.apple.com and gs-loc-cn.apple.com;
Intercept gs-loc(-cn).apple.com/clls/wloc responses, read the same persistent data, and modify the WLOC response;
Publish an importable module and verify query, save, clear, and location restoration on a real device.

The app validates only the configuration endpoint's HTTP status, JSON shape, and coordinate round trip. It does not manage the third-party client's certificate, MITM, VPN, or proxy state.

Do not enable App Mode interception and Third-party Proxy Mode interception at the same time.

Runtime Modes

App Mode

Suitable for:

Wi-Fi-only device testing;
Local testing without a third-party proxy client;
Workflows that need in-app proxy, certificate, and environment guidance.

Requirements:

An iOS device;
A Wi-Fi network that permits manual HTTP proxy configuration;
Installation and trust of the local CA;
Completion of the in-app proxy and environment checks.

Third-party Proxy Mode

Suitable for:

Tests that need Wi-Fi, 4G, or 5G coverage;
Existing supported proxy-client workflows;
Cases where the third-party client should keep the proxy configuration active.

Current client status:

Client	Status	Community configuration
Shadowrocket	Currently used for on-device testing	Built-in App guide
Surge	Configuration provided, not fully verified	Contributions wanted
Quantumult X	Configuration provided, not fully verified	Contributions wanted
Loon	Configuration provided, not fully verified	Contributions wanted
Stash	Configuration provided, not fully verified	Contributions wanted
Egern	Uses the Surge module, not fully verified	Contributions wanted

Community configurations are reviewed by client. Accepted submissions are linked in this table with attribution unless the contributor requests anonymous inclusion.

Module snapshots and provenance:

The selected client owns its certificates, MITM configuration, and proxy switches. Review third-party modules and scripts before importing them.

Quick Start

1. Install the App

You can use:

Your own Apple Developer signing environment;
A self-signing tool suitable for personal testing;
The unsigned IPA published in Releases;
A source build produced on macOS using the build guide.

Free self-signing environments may not provide Network Extension capabilities. App Mode therefore uses an on-device proxy plus a manual Wi-Fi HTTP proxy and does not depend on a VPN component.

Self-Signing Instructions

Release assets are unsigned IPA files and must be installed on an iPhone with a self-signing tool:

Enable sideloading support: On iOS 16 or newer, open Settings → Privacy & Security → Developer Mode, enable it, then restart and confirm when prompted. iOS 15 does not have this switch, so skip this step.
Download the IPA: Open this project's Releases and download the latest PaopaoLocationSpoofer-unsigned.ipa.
Prepare signing software: Download the appropriate Impactor build from Impactor Releases. Other tools that support self-signing and installing IPA files, such as Aisi Assistant, may also be used.
Connect and install: Connect the iPhone to the computer with a USB cable, choose “Trust This Computer” on the phone, select the downloaded IPA in the signing software, and follow that tool's instructions to sign and install it.

Impactor supports Windows, macOS, and Linux. If Windows cannot detect the device, install the Apple device drivers supplied with iTunes first. Aisi Assistant is third-party software; obtain it from its official channel and evaluate its account, certificate, and privacy risks yourself.

After installation, if iOS blocks the app from opening, go to Settings → General → VPN & Device Management and trust the corresponding developer app. A free Apple ID signature normally expires after seven days and must then be renewed.

2. First Launch

Choose App Mode or Third-party Proxy Mode;
Complete the corresponding in-app setup;
Run the environment check;
Search, tap, or drag on the map to select a test location;
Enable the test location and verify the result in the authorized test environment.

3. Restore the Real Location

App Mode:

Stop the test location;
Disable the manual HTTP proxy on the current Wi-Fi network;
Follow the in-app instructions to refresh the location environment.

Third-party Proxy Mode:

Clear the WLOC coordinates from the app;
Disable the corresponding module or proxy in the third-party client;
Restore HTTPS decryption and proxy settings according to the client documentation.

Location caches may take time to refresh. Restart the device if the system or target app continues to show an old location.

Coordinate Handling

The project stores two coordinate representations:

WGS-84: the international standard used for WLOC writes;
GCJ-02: the domestic map representation used where required.

MapKit does not expose a public API that reports whether its current runtime output uses GCJ-02 or WGS-84. The project uses a fixed-anchor query to resolve the active representation and performs controlled refreshes after blue-dot changes and explicit user actions.

Each write boundary stores a complete WGS-84/GCJ-02 pair. Rendering selects the field matching the confirmed map representation instead of repeatedly converting an already typed value.

Project Structure

App/        SwiftUI interface, MapKit, location, and runtime flow
Core/       Go proxy, certificate server, and location-response handling
Shared/     Coordinates, favorites, logs, configuration, and shared models
Resources/  Info.plist, Entitlements, and resources
Config/     Build configuration
Scripts/    Build, packaging, and validation scripts
Tests/      XCTest and Shell contract tests
docs/       Build, module, and release documentation

Building the Project

Source builds require:

macOS;
Xcode;
Xcode Command Line Tools;
XcodeGen;
Go 1.23 or newer.

Building the iOS app directly on Windows is not supported.

git clone https://github.com/xweiba/location-spoofer.git
cd location-spoofer

./build.sh

Build and run Simulator tests:

./build.sh --test

The build script generates an unsigned IPA:

dist/PaopaoLocationSpoofer-unsigned.ipa

Deploy it to a test device using your own signing and installation process.

Privacy and Security Boundaries

The project contains no telemetry or remote-control service;
The project does not automatically upload location data;
Runtime logs remain in the device App Group container and retain only the latest three days;
Issue reports are copied by the user before being submitted to GitHub;
App Mode accesses the local proxy and the environment-verification URL;
Third-party Proxy Mode may access the upstream module URL and the WLOC configuration endpoint;
The CA private key generated by the app is stored in the device Keychain;
Third-party MITM, certificates, and proxy behavior are owned by the selected client.

Do not post real locations, authentication information, CA private keys, or complete sensitive logs in public issues.

Limitations

iOS updates may change location-service behavior;
MapKit coordinate output can vary with the system, region, and location environment;
System location caches may delay visible changes;
Each third-party proxy client requires separate compatibility testing;
Not every app uses the same location API;
Not every app or service accepts test coordinates;
Behavior is not guaranteed across every network, device model, or iOS version.

Contributing

Contributions are welcome for:

Bug reports;
Feature requests;
Usage help and compatibility results;
Third-party client configurations and sanitized screenshots;
Performance improvements;
Documentation improvements;
Additional tests.

For bugs, generate a report from Settings → Support → Report Bug in the App whenever possible. The report includes:

iOS version;
App version;
Runtime mode;
Selected third-party client;
Whether the issue is reproducible;
Problem description;
Sanitized runtime logs;

Paste it into the App-generated diagnostic report field in the GitHub Issue Form.

Documentation

Feature Preview

These screenshots show the main interface and selected on-device test scenarios. Actual results depend on the iOS version, network environment, system caches, and the target app's location strategy; they are not a compatibility guarantee for every app or release.