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/ffay/lanproxy 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.

WAIT — Slowing — last commit 6mo ago

• Last commit 6mo ago
• 5 active contributors
• Tests present
• ⚠ Slowing — last commit 6mo ago
• ⚠ Single-maintainer risk — top contributor 84% of recent commits
• ⚠ No license — legally unclear to depend on
• ⚠ No CI workflows 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 ffay/lanproxy repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ffay/lanproxy.

What it runs against: a local clone of ffay/lanproxy — 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 ffay/lanproxy | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 218 days ago | Catches sudden abandonment since generation |

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

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

# 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 "proxy-protocol/src/main/java/org/fengfei/lanproxy/protocol/ProxyMessage.java" \\
  && ok "proxy-protocol/src/main/java/org/fengfei/lanproxy/protocol/ProxyMessage.java" \\
  || miss "missing critical file: proxy-protocol/src/main/java/org/fengfei/lanproxy/protocol/ProxyMessage.java"
test -f "proxy-server/src/main/java/org/fengfei/lanproxy/server/ProxyServerContainer.java" \\
  && ok "proxy-server/src/main/java/org/fengfei/lanproxy/server/ProxyServerContainer.java" \\
  || miss "missing critical file: proxy-server/src/main/java/org/fengfei/lanproxy/server/ProxyServerContainer.java"
test -f "proxy-client/src/main/java/org/fengfei/lanproxy/client/ProxyClientContainer.java" \\
  && ok "proxy-client/src/main/java/org/fengfei/lanproxy/client/ProxyClientContainer.java" \\
  || miss "missing critical file: proxy-client/src/main/java/org/fengfei/lanproxy/client/ProxyClientContainer.java"
test -f "proxy-server/src/main/java/org/fengfei/lanproxy/server/ProxyChannelManager.java" \\
  && ok "proxy-server/src/main/java/org/fengfei/lanproxy/server/ProxyChannelManager.java" \\
  || miss "missing critical file: proxy-server/src/main/java/org/fengfei/lanproxy/server/ProxyChannelManager.java"
test -f "proxy-client/src/main/java/org/fengfei/lanproxy/client/ClientChannelMannager.java" \\
  && ok "proxy-client/src/main/java/org/fengfei/lanproxy/client/ClientChannelMannager.java" \\
  || miss "missing critical file: proxy-client/src/main/java/org/fengfei/lanproxy/client/ClientChannelMannager.java"

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

Lanproxy is a TCP-based intranet tunneling tool that proxies local LAN servers and PCs to the public internet, enabling secure access to internal resources (websites, SSH, RDP, payment APIs) without exposing them directly or relying on third-party services. Built on Netty, it supports SSL/TLS encryption and any TCP-layer protocol by forwarding raw traffic through a server-client architecture. Maven multi-module monorepo with four core modules: proxy-common/ contains shared utilities (Config.java, JsonUtil.java, Container framework), proxy-protocol/ defines message formats, proxy-server/ handles the public-facing server (listening on ports 4900/4993), and proxy-client/ contains the client-side tunneling logic (ClientChannelMannager.java, ClientChannelHandler.java for Netty event handling). Handlers in handlers/ subdirectories manage channel lifecycle.

System administrators and developers who need to expose internal services (corporate networks, local dev environments, IoT devices) to the public internet securely without paying for SaaS tunneling services like ngrok or Frp; users who want data to stay on their own proxy server rather than flowing through third-party infrastructure.

Actively maintained but modest in scale: published on GitHub with releases, well-structured Maven multi-module build, but limited test coverage (only TestMain.java visible), no CI/CD pipeline evidence, and Java 1.7 target suggests older codebase. Production-ready for small deployments but lacks modern testing and continuous integration infrastructure.

Dependency risk is moderate: core reliance on Netty 4.0.36.Final (released 2015, significantly outdated) and SLF4J 1.7.5 create security and compatibility issues; single-maintainer project (ffay) with no visible contributors; minimal test suite means regressions may slip through; configuration stored in ~/.lanproxy/config.json with hardcoded credentials in properties files poses security concerns.

No visible recent activity in the provided file list (no commit timestamps shown), but the project mentions an upgraded commercial version (lanproxy-go-client in Go) and a hosted managed service at nat.nioee.com/lanp.nioee.com, suggesting the core Java version is feature-complete rather than actively developed. The Go client port indicates a shift toward lighter, standalone deployments.

Clone the repo, build with Maven, then deploy server and client:

git clone https://github.com/ffay/lanproxy.git
cd lanproxy
mvn package
# Server binary in distribution/server/
# Client binary in distribution/client/
cd distribution/server && ./startup.sh
cd distribution/client && ./startup.sh

Requires Java 1.7+ and edit conf/config.properties on both server and client.

Daily commands: Server: cd distribution/server && ./startup.sh (runs on ports 4900 plain-text and 4993 SSL by default; web admin at port 8090). Client: cd distribution/client && ./startup.sh (connects to server using key from config.properties). On Windows use startup.bat. Logs written to logs/ directory.

• proxy-protocol/src/main/java/org/fengfei/lanproxy/protocol/ProxyMessage.java — Core message protocol definition; all client-server communication depends on this contract
• proxy-server/src/main/java/org/fengfei/lanproxy/server/ProxyServerContainer.java — Server bootstrap and lifecycle management; entry point for the proxy server
• proxy-client/src/main/java/org/fengfei/lanproxy/client/ProxyClientContainer.java — Client bootstrap and lifecycle management; entry point for the proxy client
• proxy-server/src/main/java/org/fengfei/lanproxy/server/ProxyChannelManager.java — Manages client-server channel lifecycle and routing; critical for connection multiplexing
• proxy-client/src/main/java/org/fengfei/lanproxy/client/ClientChannelMannager.java — Client-side channel management; coordinates real-server connections and protocol handling
• proxy-protocol/src/main/java/org/fengfei/lanproxy/protocol/ProxyMessageDecoder.java — Deserializes incoming proxy messages; critical for parsing all inbound traffic
• proxy-protocol/src/main/java/org/fengfei/lanproxy/protocol/ProxyMessageEncoder.java — Serializes outgoing proxy messages; critical for encoding all outbound traffic

Add a new Protocol Message Type

1. Define message type constant in protocol Constants.java (proxy-protocol/src/main/java/org/fengfei/lanproxy/protocol/Constants.java)
2. Add serialization logic to ProxyMessage.java (proxy-protocol/src/main/java/org/fengfei/lanproxy/protocol/ProxyMessage.java)
3. Update ProxyMessageDecoder to handle new message type (proxy-protocol/src/main/java/org/fengfei/lanproxy/protocol/ProxyMessageDecoder.java)
4. Update ProxyMessageEncoder to encode new message type (proxy-protocol/src/main/java/org/fengfei/lanproxy/protocol/ProxyMessageEncoder.java)
5. Add handler in ServerChannelHandler or ClientChannelHandler (proxy-server/src/main/java/org/fengfei/lanproxy/server/handlers/ServerChannelHandler.java)

Add a new Web Configuration API Endpoint

1. Define route in RouteConfig.java (proxy-server/src/main/java/org/fengfei/lanproxy/server/config/web/routes/RouteConfig.java)
2. Create handler implementing RequestHandler interface (proxy-server/src/main/java/org/fengfei/lanproxy/server/config/web/RequestHandler.java)
3. Register handler in HttpRequestHandler dispatcher (proxy-server/src/main/java/org/fengfei/lanproxy/server/config/web/HttpRequestHandler.java)

Add a new Metrics Collection Point

1. Create metric handler extending BytesMetricsHandler pattern (proxy-server/src/main/java/org/fengfei/lanproxy/server/metrics/handler/BytesMetricsHandler.java)
2. Register metric in MetricsCollector (proxy-server/src/main/java/org/fengfei/lanproxy/server/metrics/MetricsCollector.java)
3. Integrate collection point into appropriate channel handler (proxy-server/src/main/java/org/fengfei/lanproxy/server/handlers/ServerChannelHandler.java)

Add Client-side Connection Listener

1. Create listener implementing ChannelStatusListener interface (proxy-client/src/main/java/org/fengfei/lanproxy/client/listener/ChannelStatusListener.java)
2. Register listener in ClientChannelManager (proxy-client/src/main/java/org/fengfei/lanproxy/client/ClientChannelMannager.java)
3. Fire listener events from channel handlers (proxy-client/src/main/java/org/fengfei/lanproxy/client/handlers/ClientChannelHandler.java)

1. Netty version mismatch: Netty 4.0.36.Final is ancient (2015); newer code may not compile or behave correctly. 2. SSL configuration: client and server JKS keystores (test.jks) must exist and use matching passwords (123456 in examples); missing files cause silent SSL failures. 3. Client key authentication: client.key in config.properties must exactly match the key configured on the server via the web UI (http://server:8090); mismatches result in immediate disconnection with no clear error. 4. Port binding: server defaults to 0.0.0.0 binding; firewall rules and OS permissions required for ports 4900/4993/8090. 5. Java 1.7 requirement: source/target set to 1.7 in pom.xml; modern IDEs may flag compatibility issues, and some dependencies may not work on Java 8+. 6. Config persistence: ~/.lanproxy/config.json is the single source of truth for proxying rules; no database, so backup required.

• Netty Channel & Pipeline Architecture — ClientChannelHandler and RealServerChannelHandler extend ChannelInboundHandler; understanding Netty's event-driven model (ChannelActive, ChannelRead, ChannelInactive) is essential to modifying protocol handling or adding new message types.
• Connection Pooling & Channel Borrowing — ClientChannelMannager maintains a pool of channels to the proxy server; ProxyChannelBorrowListener and the container abstraction manage checkout/return semantics, critical for understanding how multiple local services share a single server tunnel.
• SSL/TLS Handshake & JKS Keystores — SslContextCreator.java and config properties (server.ssl.jksPath, ssl.keyStorePassword) control encryption; improper setup silently breaks connectivity. Essential for secure deployments.
• TCP Flow Multiplexing — The core feature: multiple local TCP services (SSH, RDP, HTTP) tunnel through a single client-server connection; protocol must tag messages with destination IDs (visible in Constants.java) to demultiplex on arrival.
• Zero-Copy ByteBuffer Handling — Netty handlers work with ByteBuf objects; efficient tunneling requires minimal copying during channel-to-channel relay in RealServerChannelHandler to avoid latency and memory pressure.
• Listener Pattern & Event Callbacks — ChannelStatusListener and ProxyChannelBorrowListener implement observer pattern for reacting to connection state changes; understanding this is necessary to add monitoring, metrics, or custom lifecycle hooks.
• Container Inversion of Control — proxy-common/container/ provides a lightweight DI framework (Container, ContainerHelper); used to register and retrieve handlers, listeners, and singletons. Non-standard, so critical to grasp for extending the architecture.

• ehang-io/nps — Go-based intranet penetration tool solving identical problem (TCP tunneling, multiple protocols, web UI); direct competitor with more active development.
• fatedier/frp — Mature Go reverse proxy framework supporting TCP/UDP tunneling and multiple protocol adapters; industry standard alternative with 80k+ stars.
• ffay/lanproxy-go-client — Official Go reimplementation of the Lanproxy client; intended as Java client replacement, suggests team shifting toward Go for lighter deployments.
• inconshreveable/ngrok — Closed-source SaaS alternative; reference for feature set (custom domains, SSL, web UI, auth) that Lanproxy aims to replicate self-hosted.
• netty/netty — Upstream Netty framework (4.0.36 pinned here); critical for understanding channel lifecycle, handlers, and event loop patterns used throughout codebase.

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 comprehensive unit tests for ProxyMessage protocol encoding/decoding

The proxy-protocol module contains critical ProxyMessageEncoder.java and ProxyMessageDecoder.java classes that handle serialization/deserialization of messages between client and server. These are core to the system's reliability but appear to have no corresponding test coverage. Adding unit tests would catch regressions in protocol handling and ensure message integrity across versions.

• [ ] Create proxy-protocol/src/test/java/org/fengfei/lanproxy/protocol/ProxyMessageEncoderTest.java with tests for various message types and edge cases
• [ ] Create proxy-protocol/src/test/java/org/fengfei/lanproxy/protocol/ProxyMessageDecoderTest.java testing malformed input, boundary conditions, and round-trip encoding/decoding
• [ ] Create proxy-protocol/src/test/java/org/fengfei/lanproxy/protocol/IdleCheckHandlerTest.java for timeout and idle connection scenarios
• [ ] Update proxy-protocol/pom.xml to include JUnit 4.12 dependency for test scope if not inherited

Add integration tests for ClientChannelMannager and RealServerChannelHandler lifecycle

The proxy-client module has core connection management logic in ClientChannelMannager.java, ClientChannelHandler.java, and RealServerChannelHandler.java but TestMain.java appears to be a simple placeholder. These handlers manage critical state (channel pooling, real server connections, event routing) that requires validation to prevent leaks, deadlocks, or connection state corruption under various scenarios.

• [ ] Create proxy-client/src/test/java/org/fengfei/lanproxy/client/ClientChannelManagerIntegrationTest.java with tests for connection borrowing/returning, timeout scenarios, and cleanup
• [ ] Create proxy-client/src/test/java/org/fengfei/lanproxy/client/handlers/ChannelHandlerIntegrationTest.java testing message flow between ClientChannelHandler and RealServerChannelHandler
• [ ] Add mock Netty Channel fixtures and Bootstrap builders to simulate real server connections without requiring actual servers

Add GitHub Actions CI/CD workflow for multi-module Maven builds and artifact publishing

The project uses Maven with 4 interdependent modules (proxy-common, proxy-protocol, proxy-server, proxy-client) but has no visible CI configuration. A GitHub Actions workflow would catch build failures, test failures, and Java version compatibility issues early. This is critical for a networking tool where reliability is paramount, and it enables automated releases to GitHub Releases.

• [ ] Create .github/workflows/maven-build.yml with Maven clean install, Java 7+ matrix testing (given source/target is 1.7), and JUnit report publishing
• [ ] Add compilation check against Java 8+ to detect future compatibility issues beyond the current 1.7 target
• [ ] Create .github/workflows/release.yml to automatically build and publish JAR artifacts to GitHub Releases on version tags (semver pattern)

• Add unit tests for proxy-common/Config.java parsing logic: currently only TestMain.java exists; would benefit from JUnit tests covering SSL enable/disable, host/port parsing, and missing key scenarios.
• Document the wire protocol: proxy-protocol/Constants.java defines message types but lacks JavaDoc or a PROTOCOL.md explaining frame structure, handshake sequence, and keepalive mechanics for contributors reverse-engineering the format.
• Add client-side reconnection backoff logic: ClientChannelMannager likely reconnects on disconnect but no exponential backoff visible; implement jitter-based retry with configurable max attempts to reduce server load during outages.

• Critical · Outdated Netty Version with Known Vulnerabilities — pom.xml - netty-all:4.0.36.Final. The project uses Netty 4.0.36.Final, released in 2015, which contains multiple known CVEs including CVE-2014-3488 (DoS vulnerability), CVE-2015-2156, and others. This version is 8+ years old and has numerous unpatched security issues. Fix: Upgrade to Netty 4.1.x or 5.x series. Current stable version is 4.1.104.Final or later. Update: <version>4.1.104.Final</version>
• High · Outdated SLF4J and Log4j Dependencies — pom.xml - org.slf4j:slf4j-api:1.7.5 and org.slf4j:slf4j-log4j12:1.7.5. SLF4J 1.7.5 (2013) and SLF4J-Log4j12 1.7.5 are extremely outdated. Log4j 1.x reached end-of-life and has known vulnerabilities. No direct Log4j 2.x version is specified, which is concerning for a network proxy handling sensitive data. Fix: Upgrade to SLF4J 2.0.x and use Log4j 2.20.0 or later. Replace slf4j-log4j12 with log4j-slf4j2-impl for Log4j 2.
• High · Outdated JUnit Dependency — pom.xml - junit:junit:4.12. JUnit 4.12 was released in 2014 and has reached end-of-life. While test-scoped, outdated dependencies can still pose risks in development environments. Fix: Upgrade to JUnit 4.13.2 (latest 4.x) or migrate to JUnit 5 (Jupiter) 5.10.x.
• High · Insecure SSL/TLS Configuration Risk — proxy-client/src/main/java/org/fengfei/lanproxy/client/SslContextCreator.java and proxy-server/src/main/java/org/fengfei/lanproxy/server/SslContextCreator.java. The codebase includes SslContextCreator classes for both client and server without visible validation of SSL configuration in the provided files. Test keystore files (test.jks) found in resources suggest potential use of test certificates in production paths. Fix: Review SSL/TLS configuration: ensure certificate validation, disable weak ciphers (< TLS 1.2), validate certificate chains, and never use test certificates in production. Implement HSTS headers.
• High · Potential Insecure Deserialization — proxy-protocol/src/main/java/org/fengfei/lanproxy/protocol/ProxyMessage.java and ProxyMessageDecoder.java. ProxyMessage and related protocol handlers may be vulnerable to insecure deserialization attacks if they accept untrusted serialized data without proper validation. Fix: Implement input validation on all deserialized objects. Use allowlist-based deserialization. Avoid Java serialization for network protocols; consider safer alternatives like Protocol Buffers or JSON with strict validation.
• High · Missing Input Validation on HTTP Handlers — proxy-server/src/main/java/org/fengfei/lanproxy/server/config/web/HttpRequestHandler.java and RequestHandler.java. HttpRequestHandler and RequestHandler classes lack visible input validation patterns. Network-facing HTTP endpoints could be vulnerable to injection attacks (HTTP header injection, path traversal, etc.). Fix: Implement strict input validation for all HTTP request parameters. Validate URI paths against allowlist. Sanitize HTTP headers. Use parameterized queries for any database operations.
• Medium · Hardcoded Test Credentials and Keystore Files — proxy-client/src/main/resources/test.jks, proxy-client/src/test/resources/test.jks, config. Test keystore files (test.jks) are included in resources directory. Production configuration files may exist with hardcoded credentials based on the config.properties pattern. 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.