If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/geph-official/geph4-client shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

AVOID — Looks unmaintained — solo project with stale commits

• GPL-3.0 licensed
• CI configured
• ⚠ Stale — last commit 1y ago
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live geph-official/geph4-client repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/geph-official/geph4-client.

What it runs against: a local clone of geph-official/geph4-client — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in geph-official/geph4-client | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 479 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of geph-official/geph4-client. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/geph-official/geph4-client.git
#   cd geph4-client
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of geph-official/geph4-client and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "geph-official/geph4-client(\\.git)?\\b" \\
  && ok "origin remote is geph-official/geph4-client" \\
  || miss "origin remote is not geph-official/geph4-client (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/main.rs" \\
  && ok "src/main.rs" \\
  || miss "missing critical file: src/main.rs"
test -f "src/connect.rs" \\
  && ok "src/connect.rs" \\
  || miss "missing critical file: src/connect.rs"
test -f "src/connect/tunnel.rs" \\
  && ok "src/connect/tunnel.rs" \\
  || miss "missing critical file: src/connect/tunnel.rs"
test -f "src/lib.rs" \\
  && ok "src/lib.rs" \\
  || miss "missing critical file: src/lib.rs"
test -f "src/config.rs" \\
  && ok "src/config.rs" \\
  || miss "missing critical file: src/config.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 479 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~449d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/geph-official/geph4-client"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

geph4-client is a command-line Rust client for Geph (迷霧通), a modular circumvention system designed to bypass national-level Internet filtering like the Great Firewall. It establishes encrypted tunnels via sosistab2 Multiplex sessions to exit servers, intelligently routing through dynamically maintained bridge servers when direct connections are blocked, and exposes SOCKS5/HTTP proxies and VPN interfaces to the local system. Single-crate Rust library/binary (src/ contains all source, with src/lib.rs as library entry and src/main.rs as CLI). Modular structure: src/connect/ handles tunnel logic and proxies (tunnel.rs, socks5.rs, dns.rs, vpn.rs, stats/), src/china/ manages GFW-specific routing, src/config.rs manages credentials, src/fronts.rs handles gateway selection. Build artifacts are C-compatible (crate-type=["staticlib","lib"] in Cargo.toml) for FFI binding.

End users in censored regions (especially China) who need reliable Internet access, and developers maintaining or forking censorship circumvention infrastructure. Contributors are typically experienced Rust engineers working on protocol-level networking or security-critical systems.

Production-ready but actively developed. The codebase is at version 4.99.32 (suggesting maturity), uses modern Rust 2021 edition, has CI/CD pipelines (GitHub Actions workflows in .github/workflows/), and integrates with ecosystem projects (geph4-protocol, sosistab2). However, no public test suite is visible in the file list, and the maintainer count appears limited (nullchinchilla listed as sole author).

Moderate-to-high risk for production use: dependencies on external crates for critical functionality (sosistab2, geph5-client, mizaru, sillad) where upstream changes could break compatibility; VPN/proxy code handles raw socket manipulation (socket2, pnet_packet) requiring careful security review; no visible public test coverage; limited visible issue/PR discussion suggests small maintenance surface. Single-maintainer risk is present (nullchinchilla@pm.me).

Active maintenance at v4.99.32 with recent dependency bumps (anyhow, structopt, chrono, tokio, geph5-client 0.2.36). CI workflow upload.yaml suggests automated releases. The codebase integrates geph5-client as a dependency (suggesting migration planning toward geph5), but primary development remains on geph4 protocol. REFACTOR.md in root indicates ongoing refactoring efforts.

Install Rust, then: cargo install geph4-client. Or clone and build: git clone https://github.com/geph-official/geph4-client && cd geph4-client && cargo build --release. View CLI options with geph4-client -h or run: geph4-client connect --exit-server 2.mtl.ca.ngexits.geph.io auth-password --username public5 --password public5

Daily commands: CLI-only project: cargo run --release -- connect --exit-server <server> auth-password --username <user> --password <pass>. For library use (FFI): build with cargo build --release --lib, then link against target/release/libgeph4client.a. No dev server; this is a client binary.

• src/main.rs — Entry point for the CLI application that orchestrates all subcommands (connect, sync, etc.); understand this first to grasp user-facing functionality.
• src/connect.rs — Core connection orchestration logic that manages tunnel establishment, bridge server proxying, and exit server communication; the heart of the circumvention system.
• src/connect/tunnel.rs — Low-level tunnel abstraction managing obfuscated UDP protocol (sosistab2) and encrypted communication; critical for understanding protocol handling.
• src/lib.rs — Library root exposing the C interface (geph4client) and coordination between modules; required for FFI and library consumers.
• src/config.rs — Configuration management for user credentials, server endpoints, and protocol settings; essential for understanding state persistence.
• src/fronts.rs — Bridge server discovery and dynamic proxy fronting logic that bypasses blocked exit servers; critical for resilience.
• Cargo.toml — Defines all external dependencies and build artifacts (staticlib + dylib); must understand target platforms and version constraints.

Add a new proxy protocol or local service

1. Create a new module file in src/connect/ (e.g., src/connect/myproto.rs) implementing async service loop (src/connect/myproto.rs)
2. Declare and instantiate the module in src/connect.rs; integrate into the tunnel spawn logic (src/connect.rs)
3. Add CLI argument parsing in src/main.rs to pass configuration (port, etc.) to connect subcommand (src/main.rs)

Add geolocation-specific routing logic

1. Extend src/china/mod.rs with new region detector and routing rules (or create src/region/mod.rs) (src/china/mod.rs)
2. Add blocklist/allowlist file (e.g., src/china/region-ips.txt) and loader in mod.rs (src/china/china-ips.txt)
3. Integrate region detector into src/connect/dns.rs or src/fronts.rs for dynamic exit selection (src/connect/dns.rs)

Add a new metrics or telemetry export

1. Extend src/connect/stats.rs to define new metric types and aggregation logic (src/connect/stats.rs)
2. Update src/connect/stats/gatherer.rs to capture new data from tunnel/protocol (src/connect/stats/gatherer.rs)
3. Export metric endpoint or callback in src/connect.rs main loop or as CLI flag (src/connect.rs)

Add support for a new bridging mechanism

1. Create new bridge protocol handler (e.g., src/connect/bridge_websocket.rs) (src/connect/bridge_websocket.rs)
2. Integrate into src/fronts.rs bridge discovery and selection logic (src/fronts.rs)
3. Add configuration option in src/config.rs and CLI flag in src/main.rs (src/config.rs)

• Rust + async-std/tokio — High-performance, memory-safe concurrent networking required for real-time tunnel proxying; Rust prevents buffer overflows in security-critical code.
• sosistab2 (obfuscated UDP protocol) — Evades DPI/censorship by masquerading tunnel traffic as non-VPN data; key differentiator from standard VPN protocols.
• Dynamic bridge fronting — When primary exit servers are blocked, transparently routes through unblocked proxy bridges to maintain availability in hostile networks.
• SOCKS5 + local DNS resolver — Standard interface for client applications; local DNS prevents ISP/firewall DNS hijacking and censorship.
• C FFI (staticlib + dylib) — Enables integration into iOS, Android, Windows, and macOS GUI clients via native bindings.

• Single-process tunnel + proxy + stats (no separate daemon)

  • Why: Simplifies deployment and reduces complexity; faster startup.
  • Consequence: CLI blocks until user interrupts; harder to integrate with systemd/launchd for auto-start.

• Blocklist-based China routing (static domain/IP lists)

  • Why: Minimal latency for route decision; works offline.
  • Consequence: Blocklists must be manually updated via sync command; cannot adapt to real-time censorship changes without re-release.

• Bridge fronting via transparent HTTP proxy (fronts.rs)

  • Why: Reuses standard HTTP (harder to block) without modifying tunnel protocol.
  • Consequence: Adds extra HTTP parsing overhead; only works for HTTP-aware exit servers.

• Credentials stored in plaintext config file (config.rs)

  • Why: Simplicity; users can edit config directly.
  • Consequence: High security risk on multi-user machines; recommend OS keyring integration as future work.

• Does not provide GUI (CLI-only); GUI clients are separate repositories (geph4-gui, etc.

No env var discovery in snippet, but infer from structopt usage that CLI args are required (exit-server, username, password). Bridge updates depend on external Geph infrastructure (bridge-phalanx servers); offline usage impossible. GFW detection is heuristic (china-ips.txt, china-domains.txt) and may drift. FFI crate requires careful C binding (geph4client.h exists but not listed in detail; check build.rs for codegen). sosistab2 and geph5-client are external and may have version lock requirements (patch.crates-io commented out suggests local development mode is conditional). TLS rustls 0.19 is pinned (not latest; check for CVEs).

• Sosistab2 Multiplex — This is the underlying datagram-based multiplexing protocol that geph4-client uses instead of TCP; understanding its unreliable nature and route switching is essential for debugging tunnel instability
• Bridge pool management & dynamic route switching — geph4-client actively monitors which bridges/routes are blocked and swaps them in real-time (see src/connect/tunnel/getsess.rs); this is the core anti-blocking mechanism
• GFW detection & geofencing (China-specific routing) — If the client detects it's in China (via IP/domain checks), it forces bridge-only routes; this conditional logic in src/china/mod.rs is specific to geph's threat model
• SOCKS5 and HTTP proxy protocols — geph4-client exposes SOCKS5 (src/connect/socks5.rs) and HTTP proxies locally; understanding these protocols is needed to extend proxy support or debug client-side connectivity
• x25519 key exchange & ed25519 signatures — Geph uses these elliptic-curve cryptographic primitives (via x25519-dalek and ed25519-dalek) for session establishment and auth; critical for understanding security model
• Async Rust with smol runtime — geph4-client uses the smol async executor (lightweight alternative to tokio) for concurrent tunnel/proxy management; understanding async-await patterns is required for core contributions
• VPN packet forwarding (TUN/TAP device handling) — src/connect/vpn.rs routes VPN packets through the tunnel via socket2; requires knowledge of platform-specific packet capture (likely via geph-nat dependency) and raw socket manipulation

• geph-official/sosistab2 — Core dependency providing unreliable datagram Multiplex session layer; essential to understand for tunnel debugging
• geph-official/bridge-phalanx — Companion service that provides the bridge servers dynamically used by geph4-client to route around blocks
• geph-official/geph4-protocol — Protocol definitions and serialization for geph4 auth, exit server communication, and bridge pool updates
• geph-official/geph5-client — Successor codebase (already a dependency in this project); shows migration path and newer architectural patterns
• getlantern/lantern — Alternative circumvention client with similar goals (anti-censorship) and publicly readable codebase for comparative architecture

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for DNS resolution in src/connect/dns.rs

The DNS module is critical for circumvention as it handles domain resolution in censored environments, but there are no visible test files. Given the complexity of handling both blocked and unblocked domains (as evidenced by src/china/china-domains.txt), adding comprehensive tests would prevent regressions in DNS poisoning detection and fallback mechanisms.

• [ ] Create src/connect/dns/tests.rs with test cases for blocked domain detection
• [ ] Add tests for DNS fallback mechanisms when primary servers are unavailable
• [ ] Test integration between dns.rs and china-domains.txt filtering logic
• [ ] Add tests for concurrent DNS query handling to ensure thread-safety

Implement integration tests for VPN and SOCKS5 tunnel connectivity in src/connect/

The repository has three major connection types (vpn.rs, socks5.rs, tunnel.rs) but lacks visible integration tests. These modules handle the core circumvention tunneling and need automated testing to ensure exit server connections work correctly across platforms, especially since the repo supports iOS, macOS, and Windows builds.

• [ ] Create tests/integration_tunnel.rs to test SOCKS5 proxy establishment
• [ ] Add tests for tunnel.rs connection establishment and data forwarding
• [ ] Test VPN mode connection lifecycle in tests/integration_vpn.rs
• [ ] Add platform-specific tests for Windows WinDivert integration (windows-lib/)

Add GitHub Actions workflow for cross-platform builds with status badges

The repo has Cross.toml and cross-setup.sh for cross-compilation, plus build scripts for iOS and macOS (ios_build.sh, osx_build.sh), but .github/workflows/upload.yaml appears to be the only build workflow. A comprehensive CI workflow would catch platform-specific compilation errors early, especially important given the complexity of supporting Windows (WinDivert), iOS, macOS, and Linux targets.

• [ ] Create .github/workflows/cross-compile.yaml to test builds for arm64, armv7, x86_64 targets
• [ ] Add platform-specific job in upload.yaml for iOS build using ios_build.sh
• [ ] Add macOS-specific job to validate osx_build.sh succeeds
• [ ] Include Windows build validation with WinDivert library linking

• Add integration tests for SOCKS5 proxy server (src/connect/socks5.rs): currently no test coverage visible; write tests that spawn a local tunnel, connect a SOCKS5 client, and verify packet forwarding.
• Document bridge pool update logic in src/connect/tunnel/getsess.rs: add inline comments explaining how routes are ranked, when bridges are swapped out, and timeout handling for blocked routes.
• Implement DNS cache statistics in src/connect/stats/gatherer.rs: track query hit/miss rates and add metrics export to complement existing connection stats.

• High · Outdated Rustls Dependency — Cargo.toml - rustls = "0.19.1". The project uses rustls 0.19.1, which is significantly outdated. Current stable versions are 0.21.x and 0.22.x. Version 0.19.1 may contain unpatched security vulnerabilities and lacks modern cryptographic improvements. Fix: Update rustls to the latest stable version (0.22.x or later). Review the rustls changelog for any breaking changes and update code accordingly.
• High · Outdated Tokio Dependency (Truncated) — Cargo.toml - tokio dependency definition. The tokio dependency in Cargo.toml appears truncated (version string cut off: "tokio = { version = "1.33.0", f"). This incomplete dependency specification could cause build failures or unintended version resolution. Fix: Complete the tokio dependency specification. Ensure the full feature list and version constraint is properly defined.
• Medium · Insecure Random Number Generation — Cargo.toml - rand = "0.7.3". The project uses rand 0.7.3, which is outdated. Current version is 0.8.x+. Older versions may have had security fixes that are not present in this release. Fix: Update to rand 0.8.x or later. Review the migration guide for any API changes.
• Medium · Outdated SHA2 Dependency — Cargo.toml - sha2 = "0.9.9". The project uses sha2 0.9.9, released in 2020. Current versions are 0.10.x+. While SHA-2 is still cryptographically secure, newer versions may include performance improvements and security fixes. Fix: Evaluate and update sha2 to 0.10.x or later if compatible with the codebase.
• Medium · Outdated Ed25519-Dalek Dependency — Cargo.toml - ed25519-dalek = { version = "2", ... }. The project uses ed25519-dalek 2.x without specific patch version lock. This cryptographic library should be carefully managed to ensure compatibility and security across updates. Fix: Pin to a specific patch version (e.g., 2.1.1) rather than using a flexible version constraint for critical cryptographic dependencies.
• Medium · Missing Cargo.lock Security Considerations — Cargo.toml - [patch.crates-io] section. While Cargo.lock exists, library crates (as evidenced by [lib] section) should ensure dependencies are reproducibly locked. The presence of patch.crates-io sections with commented-out local paths suggests complex dependency management that could introduce supply chain risks. Fix: Document the dependency patching strategy. Ensure all dependencies are properly audited using cargo audit before committing changes.
• Medium · Potential Unsafe Code in Cryptographic Operations — src/ (entire codebase). The project implements a censorship circumvention tool with cryptographic operations (x25519, ed25519). Without visible code review, unsafe blocks could be present in critical security paths. Fix: Run cargo clippy --all-targets --all-features and cargo audit. Conduct security review of all unsafe blocks, particularly in networking and cryptographic modules (src/connect/, src/socks2http/).
• Medium · Insecure Direct Object References in VPN Module — src/connect/vpn.rs, src/connect/port_forwarder.rs. The VPN module (src/connect/vpn.rs) and port forwarding (src/connect/port_forwarder.rs) handle low-level network operations. Insufficient input validation could lead to network-level attacks. Fix: Implement strict input validation for all network parameters. Review for potential buffer overflows and integer overflows in packet handling.
• Low · Hardcoded China-Specific Configuration — undefined. The codebase includes China-specific domain and IP lists (src/china/china-domains.txt, src/china Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.