location-spoofer/README.en.md

<div align="center">

# 📍 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.

> ⚠️ **Starting with iOS 27 beta 6, the system blocks MITM interception of `gs-loc.apple.com`.** This project is
> temporarily unusable on that version and later betas until a workaround is found.

[![iOS 15+](https://img.shields.io/badge/iOS-15%2B-111111?logo=apple)](project.yml)
[![Swift 5.9](https://img.shields.io/badge/Swift-5.9-F05138)](project.yml)
[![Go 1.23+](https://img.shields.io/badge/Go-1.23%2B-00ADD8?logo=go)](Core/go.mod)
[![Version](https://img.shields.io/badge/version-v1.0.5-2563EB)](docs/CHANGELOG.md)

[Features](#feature-overview) ·
[How It Works](#how-it-works) ·
[Quick Start](#quick-start) ·
[Build](#building-the-project) ·
[中文](README.md)

</div>

> [!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.

```text
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.

```text
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:

```text
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:

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

Failures use:

```json
{
  "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:

1. Add an HTTP request script for `gs-loc.apple.com/wloc-settings/save` that parses the parameters and returns the
   specified JSON;
2. Store coordinates, accuracy, and optional state in the client's persistent storage;
3. Enable HTTPS decryption for `gs-loc.apple.com` and `gs-loc-cn.apple.com`;
4. Intercept `gs-loc(-cn).apple.com/clls/wloc` responses, read the same persistent data, and modify the WLOC response;
5. 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.

Modules and scripts are now hosted by this repository. The original
`Yu9191/wloc` repository was deleted and remains attribution only, not a runtime dependency:

- [Third-party module documentation](docs/THIRD_PARTY_MODULES.md)

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](docs/BUILD.md).

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:

1. **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.
2. **Download the IPA**: Open this project's [Releases](https://github.com/xweiba/location-spoofer/releases) and download
   the latest `PaopaoLocationSpoofer-unsigned.ipa`.
3. **Prepare signing software**: Download the appropriate Impactor build from
   [Impactor Releases](https://github.com/claration/Impactor/releases). Other tools that support self-signing and installing
   IPA files, such as Aisi Assistant, may also be used.
4. **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

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

### 3. Restore the Real Location

App Mode:

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

Third-party Proxy Mode:

1. Clear the WLOC coordinates from the app;
2. Disable the corresponding module or proxy in the third-party client;
3. 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

```text
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.

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

./build.sh
```

Build and run Simulator tests:

```bash
./build.sh --test
```

The build script generates an unsigned IPA:

```text
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 module URLs hosted by this repository 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](https://github.com/xweiba/location-spoofer/issues/new?template=bug-report.yml);
- [Feature requests](https://github.com/xweiba/location-spoofer/discussions/categories/%E5%8A%9F%E8%83%BD%E5%BB%BA%E8%AE%AE);
- [Usage help and compatibility results](https://github.com/xweiba/location-spoofer/discussions/categories/%E4%BD%BF%E7%94%A8%E5%B8%AE%E5%8A%A9);
- [Third-party client configurations and sanitized screenshots](https://github.com/xweiba/location-spoofer/discussions/categories/%E7%AC%AC%E4%B8%89%E6%96%B9%E9%85%8D%E7%BD%AE%E5%88%86%E4%BA%AB);
- 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

- [Build guide](docs/BUILD.md)
- [Third-party module documentation](docs/THIRD_PARTY_MODULES.md)
- [Changelog](docs/CHANGELOG.md)
- [中文文档](README.md)
- [GitHub Issues](https://github.com/xweiba/location-spoofer/issues)

## 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.

<table>
  <tr>
    <th>Main interface</th>
    <th>Apple Maps test</th>
    <th>Amap test</th>
  </tr>
  <tr>
    <td><img src="images/主界面.jpg" alt="Location Spoofer map selection interface" width="220"></td>
    <td><img src="images/Apple%20Map.jpg" alt="Apple Maps location test scenario" width="220"></td>
    <td><img src="images/高德地图.jpg" alt="Amap location test scenario" width="220"></td>
  </tr>
  <tr>
    <th>WeChat test</th>
    <th>DingTalk test</th>
    <th>Apple Watch scenario test</th>
  </tr>
  <tr>
    <td><img src="images/微信.jpg" alt="WeChat location test scenario" width="220"></td>
    <td><img src="images/钉钉.jpg" alt="DingTalk location test scenario" width="220"></td>
    <td><img src="images/高血压.jpg" alt="Apple Watch region-feature test scenario" width="220"></td>
  </tr>
</table>

## Acknowledgements and Links

The core location-response handling approach, Go implementation, and third-party modules are based on
the following projects (`Yu9191/wloc` has since been deleted):

- [Yu9191/wloc](https://github.com/Yu9191/wloc)
- [ios-location-spoofer](https://github.com/mekos2772/ios-location-spoofer)

Thanks to the following LINUX DO users for their contributions:

- Bug fixes: [Chen Ze](https://linux.do/u/lixiaobaivv)
- Ideas and suggestions: [Alex](https://linux.do/u/_alex), [ye4241](https://linux.do/u/ye4241)

Links:

- [LINUX DO](https://linux.do/)
- [iOS-Location-Spoofer-Web](https://github.com/akudamatata/iOS-Location-Spoofer-Web)

Thanks to the open-source contributors working on iOS location-service research, network proxies, and mobile testing
tools.