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/klzgrad/naiveproxy 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.

GO — Healthy across all four use cases

• Last commit 2d ago
• 2 active contributors
• BSD-3-Clause licensed
• CI configured
• Tests present
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 99% of recent commits

_{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 klzgrad/naiveproxy repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/klzgrad/naiveproxy.

What it runs against: a local clone of klzgrad/naiveproxy — 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 klzgrad/naiveproxy | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-3-Clause | 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 ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of klzgrad/naiveproxy. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/klzgrad/naiveproxy.git
#   cd naiveproxy
#
# 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 klzgrad/naiveproxy and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-3-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-3-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-3-Clause" \\
  || miss "license drift — was BSD-3-Clause 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 "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "USAGE.txt" \\
  && ok "USAGE.txt" \\
  || miss "missing critical file: USAGE.txt"
test -f "src/BUILD.gn" \\
  && ok "src/BUILD.gn" \\
  || miss "missing critical file: src/BUILD.gn"
test -f "apk/app/build.gradle.kts" \\
  && ok "apk/app/build.gradle.kts" \\
  || miss "missing critical file: apk/app/build.gradle.kts"
test -f "apk/app/src/main/java/io/nekohasekai/sagernet/plugin/NativePluginProvider.kt" \\
  && ok "apk/app/src/main/java/io/nekohasekai/sagernet/plugin/NativePluginProvider.kt" \\
  || miss "missing critical file: apk/app/src/main/java/io/nekohasekai/sagernet/plugin/NativePluginProvider.kt"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
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/klzgrad/naiveproxy"
  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).

NaïveProxy is a censorship-resistant proxy that camouflages traffic by reusing Chromium's network stack to mimic legitimate HTTPS/HTTP2 browser connections. It defeats active probing, traffic classification, and TLS fingerprinting by making proxy traffic indistinguishable from normal Chrome browser traffic to standard frontend servers like Caddy or HAProxy. Hybrid monorepo: core C++ proxy logic in src/ (Chromium-based), Android APK wrapper in apk/ (Kotlin/Java with Gradle, integrating via NativePluginProvider.kt and BinaryProvider.kt), and CI automation in .github/workflows. The src/ directory contains the Chromium-derived network stack; apk/ contains the SageNet plugin integration.

Users in censored regions who need a proxy to bypass network filtering, and infrastructure operators deploying forwarding/proxy servers in high-surveillance environments. Developers integrating proxy capabilities into apps like Exclave, husi, NekoBox, or custom Android/Linux clients.

Production-ready and actively maintained. The repo includes CI/CD via GitHub Actions (.github/workflows/build.yml), multi-platform release binaries (Windows, Android, Linux, macOS, OpenWrt), and tracks Chromium versions via CHROMIUM_VERSION file. Regular builds and updates indicate ongoing maintenance, though single-maintainer (@klzgrad) is a risk factor.

High complexity due to tight coupling to Chromium's network stack—CHROMIUM_VERSION must stay synchronized or signatures diverge from real Chrome, defeating the evasion purpose. Dependency on Chromium's build system (gn, ninja) and large binary sizes are barriers. Single maintainer and reliance on Caddy forwardproxy fork (github.com/klzgrad/forwardproxy) for full functionality increases sustainability risk.

Active CI/CD builds tracked in .github/workflows/build.yml for multi-platform binaries. Gradle build system recently updated to Gradle 8.11.0 and Kotlin 2.2.0 in build.gradle.kts. Android integration code exists but specific recent PRs/issues are not visible in the file structure provided; check GitHub Actions logs and release timeline.

Clone and build per .github/workflows/build.yml: git clone https://github.com/klzgrad/naiveproxy.git && cd naiveproxy. For Android APK: cd apk && ./gradlew build. For server setup, follow README instructions to build the Caddy fork: xcaddy build --with github.com/caddyserver/forwardproxy=github.com/klzgrad/forwardproxy@naive.

Daily commands: Client (CLI): Download binary from releases or build via build.yml, then run with config (see USAGE.txt). Android: Build APK via cd apk && ./gradlew assembleDebug, install, configure through SageNet app. Server: Run Caddy forwardproxy fork on port 443 with Caddyfile (example in README with basic_auth and hi padding).

• README.md — Explains NaïveProxy's core purpose: using Chromium's network stack to camouflage proxy traffic with censorship resistance, establishing the project's threat model and architecture.
• USAGE.txt — Documents the client and server configuration interface; essential for understanding how to deploy and operate the proxy.
• src/BUILD.gn — Top-level GN build configuration for the Chromium-based native build; entry point for understanding the build system and dependencies.
• apk/app/build.gradle.kts — Android APK build configuration using Kotlin DSL; critical for building the mobile client variant.
• apk/app/src/main/java/io/nekohasekai/sagernet/plugin/NativePluginProvider.kt — Core Android plugin interface that bridges the Java/Kotlin Android layer with the native naiveproxy binary.
• .github/workflows/build.yml — CI/CD workflow defining how builds are automated across platforms; essential for understanding release and testing strategy.
• CHROMIUM_VERSION — Pins the exact Chromium version used; critical for reproducible builds and understanding dependency baseline.

• Chromium Network Stack (libnet, TLS, HTTP/2) (C++, OpenSSL, boringssl, HTTP/2 HPACK) — Establishes encrypted connections, handles protocol negotiation, multiplexes streams, applies traffic padding and fragmentation.
  • Failure mode: If TLS fingerprint differs from Chrome or HTTP/2 multiplexing fails, active probing or traffic classification may succeed.
• Naïve Client Proxy Handler — Intercepts user HTTP requests, wraps them into HTTP/2 streams, applies camouflage

Add a new protocol feature to the native proxy

1. Modify the Chromium network stack layer in src/base/allocator or create a new module under src/ (src/BUILD.gn)
2. Update the GN build rules to include your new C++ source files (src/BUILD.gn)
3. Test the feature in the native build via CI/CD (.github/workflows/build.yml)

Build and release for a new platform (e.g., iOS, Windows)

1. Update CHROMIUM_VERSION if needed for platform-specific fixes (CHROMIUM_VERSION)
2. Add new build target job in the CI/CD workflow (.github/workflows/build.yml)
3. Create platform-specific wrapper (e.g., apk/ equivalent for iOS) with build.gradle equivalent

Integrate naiveproxy into a new Android app

1. Implement the PluginContract interface in your app (apk/app/src/main/java/io/nekohasekai/sagernet/plugin/PluginContract.kt)
2. Use BinaryProvider to load the naiveproxy binary (apk/app/src/main/java/io/nekohasekai/sagernet/plugin/naive/BinaryProvider.kt)
3. Call into NativePluginProvider to execute proxy operations (apk/app/src/main/java/io/nekohasekai/sagernet/plugin/NativePluginProvider.kt)
4. Add required permissions in your AndroidManifest.xml (apk/app/src/main/AndroidManifest.xml)

• Chromium Network Stack (libnet, TLS, HTTP/2) — Reusing Chrome's proven network implementation defeats fingerprinting, active probing, and TLS parameter analysis by appearing identical to legitimate browser traffic.
• HTTP/2 with Traffic Multiplexing — Multiple streams over one connection mitigates website fingerprinting and traffic classification attacks through preamble parroting.
• Android Gradle + Kotlin for Mobile — Standard Android build tooling enables SagerNet plugin integration and seamless distribution via APK; Kotlin provides modern type-safe interop with Java.
• GN Build System — Chromium's native build system ensures consistent, cross-platform compilation of the C++ proxy core with proper dependency resolution.
• Application Fronting (Frontend → Server) — Hiding proxy endpoints behind normal frontend servers (e.g., CDN, web app) adds an application-layer routing layer that obscures the proxy's true identity.

• Reuse entire Chromium network stack instead of building minimal proxy

  • Why: Maximizes traffic indistinguishability and security guarantees by leveraging battle-tested, actively maintained code.
  • Consequence: Larger binary footprint, longer build times, and dependency on Chromium version pinning (CHROMIUM_VERSION).

• Android-first platform support with SagerNet plugin architecture

  • Why: Mobile is a primary target for censorship circumvention; plugin model allows integration into existing VPN/proxy apps.
  • Consequence: No built-in iOS, Windows, or macOS support in this repo; requires separate platform-specific wrappers.

• Split native core (C++) from platform wrappers (Kotlin/Java for Android)

  • Why: Allows code reuse across platforms while leveraging platform-native UI frameworks.
  • Consequence: Requires JNI glue code and careful binary distribution strategy per platform.

• Not a real VPN: operates at HTTP proxy level, not network stack level; requires per-app configuration.
• Not a Tor replacement: focuses on camouflage-via-mimicry rather than onion routing or multi-hop anonymity.
• Not cross-platform out-of-box: Android APK is primary distribution; other platforms require separate tooling.
• Not a general-purpose HTTP proxy: optimized for censorship circumvention; not suitable for corporate filtering or content caching.
• Does not implement DNS-over-HTTPS or DNS leakage mitigation: relies on caller to configure DNS properly.

Chromium version drift: CHROMIUM_VERSION must exactly match the Chromium tag used in src/; divergence breaks signature matching and defeats censorship evasion. Binary delivery: APK requires pre-compiled native binaries embedded or downloaded at runtime (BinaryProvider.kt handles this but network access may be blocked in censored regions). JNI brittleness: Android integration depends on stable JNI ABI; C++ changes can silently break APK without Kotlin-level errors. Caddy server requirement: client alone is useless; you must run github.com/klzgrad/forwardproxy fork on backend, not stock Caddy or forwardproxy, to get the hi padding layer. Build environment: full Chromium build (gn, ninja) required; simple make won't work—see build.yml for exact commands.

• Application Fronting — NaïveProxy hides behind standard frontend servers (Caddy, HAProxy) to make active probing impossible—adversaries see legitimate proxy service traffic, not a proxy server, defeating enumeration attacks.
• TLS Fingerprinting & Signature Matching — The entire premise of NaïveProxy is to defeat TLS parameter fingerprinting by reusing Chrome's exact TLS stack; understanding cipher suites, extensions, and handshake order is critical to why CHROMIUM_VERSION must stay in sync.
• HTTP/2 Traffic Multiplexing & Preamble Parroting — NaïveProxy uses HTTP/2 multiplexing to mix proxy traffic with fake Chrome browser preambles, defeating website fingerprinting attacks that analyze traffic patterns and sizes.
• Packet Padding & Length-Based Traffic Analysis — The hi layer in Caddy forwardproxy fork adds padding to obscure packet lengths, mitigating length-based statistical attacks that correlate proxy traffic to plaintext.
• JNI (Java Native Interface) — Android APK wraps C++ Chromium code via JNI; understanding JNI calling conventions (method signatures, thread safety in BinaryProvider.kt, NativePluginProvider.kt) is essential for porting or debugging Android integration.
• Forward Proxy Protocol (HTTP CONNECT & HTTP/2) — NaïveProxy implements a forward proxy that routes client traffic via HTTP CONNECT over HTTP/2, not a reverse proxy; this is key to why it works with any frontend server that understands HTTP authorization headers.
• Chromium Network Stack Reuse (Layering & ABI Stability) — The entire project depends on embedding Chromium's URL, HTTP, TLS, and socket layers; changes to Chromium ABI or removal of APIs can break NaïveProxy, so tracking CHROMIUM_VERSION and understanding the network stack architecture is non-negotiable.

• klzgrad/forwardproxy — The Caddy forwardproxy fork that adds NaïveProxy's padding layer to Caddy; required on the server side for full functionality.
• MatsuriDayo/NekoBoxForAndroid — Android app that integrates NaïveProxy as a plugin, demonstrating real-world consumption of the APK and native binary outputs.
• dyhkwong/Exclave — Another Android container/plugin framework that supports NaïveProxy, showing alternative integration patterns.
• chromium/chromium — The upstream Chromium project; NaïveProxy reuses its network stack directly, so Chromium releases determine NaïveProxy's TLS/HTTP2 signatures.
• v2ray/v2ray-core — Competing proxy/tunnel framework; contextual alternative for censorship resistance, though NaïveProxy's Chromium-based approach is harder to fingerprint.

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 Android APK Build & Release CI Workflow

The repo has a complete APK structure (apk/app/build.gradle.kts with Kotlin DSL, release.keystore, and gradle wrapper) but the .github/workflows/build.yml likely only builds the native proxy binary. A dedicated APK release workflow would automatically sign and publish releases, matching the native binary build automation. This is high-value since APK distribution is already structured but not automated.

• [ ] Review current .github/workflows/build.yml to understand existing CI patterns
• [ ] Create .github/workflows/android-apk-build.yml that builds apk/app using gradlew with release keystore
• [ ] Add conditional step to automatically upload signed APK to GitHub Releases on tag pushes
• [ ] Document APK build prerequisites (keystore path, signing config) in USAGE.txt

Add Integration Tests for NativePluginProvider.kt and PluginContract.kt

The plugin architecture (apk/app/src/main/java/io/nekohasekai/sagernet/plugin/) has provider interfaces and contracts but no visible test coverage. These Kotlin classes handle plugin loading and IPC contracts, which are critical security-sensitive code paths. Tests would ensure plugin isolation works correctly and prevent regressions when updating the plugin API.

• [ ] Create apk/app/src/test/java/io/nekohasekai/sagernet/plugin/ directory
• [ ] Add unit tests for PluginContract.kt contract parsing and validation
• [ ] Add unit tests for NativePluginProvider.kt binary resolution and loading logic
• [ ] Create apk/app/src/androidTest/ integration test for plugin provider lifecycle (mock plugin loading, path resolution)

Add Cross-Platform Build Matrix Documentation & Validation Script

The CHROMIUM_VERSION file and src/BUILD.gn suggest multi-platform builds (Chromium stack supports Linux, macOS, Windows, Android), but README.md architecture section is incomplete (cuts off at '## Architec'). A build matrix documenting supported platforms + a validation script checking build prerequisites would reduce contributor friction and failed builds.

• [ ] Complete README.md '## Architecture' section (currently truncated)
• [ ] Create BUILD_PLATFORMS.md documenting officially supported platforms, target architectures, and known limitations
• [ ] Add scripts/validate-build-env.sh to check for required tools (clang, gn, ninja) per platform
• [ ] Update .github/workflows/build.yml to reference platform requirements from BUILD_PLATFORMS.md

• Add integration tests for Android APK: write Kotlin unit tests in apk/app/src/test to verify BinaryProvider.kt correctly loads the native binary, validates its signature, and invokes basic proxy operations. Currently no test files visible in apk/.
• Document padding algorithm**: create docs/padding.md explaining the HTTP/2 preamble parroting and packet fragmentation logic in src/ with code examples; README and USAGE.txt lack technical details for developers forking the project.
• Add OpenWrt build verification**: the file list mentions OpenWrt support but no dedicated apk/openwrt or src/openwrt subdir is visible; create a cross-compile CI job in .github/workflows/build.yml for mips/arm targets and document in README.

NaïveProxy shows moderate security posture with some concerning issues. The primary risk is the hardcoded release keystore in version control, which must be remediated immediately. The use of native plugin loading creates additional attack surface that requires robust cryptographic verification. The Gradle/Kotlin dependencies appear reasonably current but should be monitored. The native code execution capabilities inherited from Chromium are well-designed but require careful integration. Documentation of security practices, automated dependency scanning, and removal of sensitive artifacts would significantly improve the security posture. Overall, this is a complex C++/Java hybrid project that reuses Chrome's security practices but introduces native plugin risks that need mitigation.

• High · Outdated Gradle Build Tools — apk/build.gradle. The build.gradle file uses Gradle 8.11.0 and Kotlin 2.2.0. While not critically outdated, these versions should be verified against the latest security patches. More importantly, the Android Gradle Plugin version 8.11.0 may have known vulnerabilities depending on the exact build date and patch level. Fix: Regularly update gradle and kotlin-gradle-plugin to the latest stable versions. Monitor security advisories from Google and JetBrains for known CVEs.
• Medium · Hardcoded Keystore File Present — apk/release.keystore. The repository contains apk/release.keystore, which appears to be a signing keystore stored in version control. This is a significant security risk if the private key has not been properly rotated or if the keystore contains production signing credentials. Fix: Remove the keystore from version control immediately. Use secure key management practices: store keystores outside the repository, use CI/CD secrets management, and rotate keys if exposure is suspected. Add *.keystore to .gitignore.
• Medium · Missing Security-Related Configuration — apk/app/src/main/AndroidManifest.xml. The AndroidManifest.xml file structure is present but content not visible. Without reviewing the manifest, potential issues could include missing security attributes like android:usesCleartextTraffic, improper exported component declarations, or missing permission restrictions. Fix: Review and ensure: (1) android:usesCleartextTraffic is set to false, (2) all exported components explicitly declare android:exported attribute, (3) permissions follow principle of least privilege, (4) appropriate Android security flags are enabled.
• Medium · Native Plugin Architecture Risk — apk/app/src/main/java/io/nekohasekai/sagernet/plugin/. The presence of NativePluginProvider.kt and BinaryProvider.kt suggests the application loads and executes native code from external sources. This introduces risks of code injection, tampering, and supply chain attacks if binary verification is not properly implemented. Fix: Implement cryptographic verification of native binaries before loading. Use code signing, checksum validation, and secure distribution channels. Implement sandboxing for native code execution. Audit the binary provider implementation for integrity checks.
• Low · Repository Purpose and Proxy Application Risk — Repository root / README.md. NaïveProxy is a proxy application designed to circumvent censorship. While legitimate in many contexts, the nature of proxy software requires careful security consideration. The mottos 'Make a fortune quietly' could indicate potential misuse. Fix: Ensure all use cases comply with applicable laws and regulations. Implement usage logging and monitoring. Document legitimate use cases clearly. Consider adding security warnings about potential misuse.
• Low · Missing SBOM and Dependency Tracking — Repository structure. While build.gradle dependencies are visible, there is no evidence of Software Bill of Materials (SBOM), dependency scanning, or documented Chromium version tracking (beyond CHROMIUM_VERSION file) for the complex Chromium-based codebase. Fix: Implement automated dependency scanning in CI/CD pipeline. Generate and maintain SBOM files. Use tools like OWASP Dependency-Check or Snyk. Document all third-party components and their security status.

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.