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/HMBSbige/ShadowsocksR-Windows 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 11mo ago

• Last commit 11mo ago
• 2 active contributors
• GPL-3.0 licensed
• CI configured
• ⚠ Slowing — last commit 11mo ago
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 99% of 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 HMBSbige/ShadowsocksR-Windows repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/HMBSbige/ShadowsocksR-Windows.

What it runs against: a local clone of HMBSbige/ShadowsocksR-Windows — 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 HMBSbige/ShadowsocksR-Windows | 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 ≤ 348 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "HMBSbige/ShadowsocksR-Windows(\\.git)?\\b" \\
  && ok "origin remote is HMBSbige/ShadowsocksR-Windows" \\
  || miss "origin remote is not HMBSbige/ShadowsocksR-Windows (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 "shadowsocks-csharp/Controller/MainController.cs" \\
  && ok "shadowsocks-csharp/Controller/MainController.cs" \\
  || miss "missing critical file: shadowsocks-csharp/Controller/MainController.cs"
test -f "shadowsocks-csharp/Model/Configuration.cs" \\
  && ok "shadowsocks-csharp/Model/Configuration.cs" \\
  || miss "missing critical file: shadowsocks-csharp/Model/Configuration.cs"
test -f "shadowsocks-csharp/Encryption/EncryptorFactory.cs" \\
  && ok "shadowsocks-csharp/Encryption/EncryptorFactory.cs" \\
  || miss "missing critical file: shadowsocks-csharp/Encryption/EncryptorFactory.cs"
test -f "shadowsocks-csharp/Controller/Service/Local.cs" \\
  && ok "shadowsocks-csharp/Controller/Service/Local.cs" \\
  || miss "missing critical file: shadowsocks-csharp/Controller/Service/Local.cs"
test -f "shadowsocks-csharp/Controller/SystemProxy.cs" \\
  && ok "shadowsocks-csharp/Controller/SystemProxy.cs" \\
  || miss "missing critical file: shadowsocks-csharp/Controller/SystemProxy.cs"

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

ShadowsocksR for Windows is a C# WinForms proxy client that routes traffic through ShadowsocksR servers using various obfuscation protocols and encryption methods. It provides local SOCKS5/HTTP proxy services, automatic PAC-based routing, server subscription management, and GFW (Great Firewall) list updates to selectively proxy traffic based on destination. Monolithic WinForms application: shadowsocks-csharp/ contains the main app split into Controller/ (proxy management, subscriptions, updates), Service/ (protocol handlers: SOCKS5, HTTP, PAC daemon, speed testing), Encryption/ (crypto primitives), and Data/ (bundled PAC files, IP lists, native libraries). UnitTest/ provides parallel test coverage. Build scripts (build.ps1, Build/DotNetDllPathPatcher.ps1) handle native dependency patching.

Windows users in restricted network environments who need circumvention tools; developers maintaining or extending the ShadowsocksR ecosystem who understand proxy protocols and obfuscation techniques. Contributors familiar with C# WinForms and networking protocols.

Actively maintained as of 2022 with established CI/CD (GitHub Actions workflow in .github/workflows/CI.yml), comprehensive unit tests in UnitTest/ folder covering DNS, encryption, subscriptions, and servers, and a mature fork history from the original BreakWa11 ShadowsocksR. Production-ready with regular updates and community support via Telegram channels.

Single-maintainer project (HMBSbige) creates succession risk; Windows-specific codebase limits cross-platform benefit; depends on bundled native DLLs (libsscrypto.dll.gz, libsscrypto64.dll.gz) that require external maintenance. The 'Ship of Theseus' description suggests significant ongoing refactoring, indicating potential for breaking changes.

Active maintenance visible through GitHub Actions CI workflow, renovate.json dependency automation, and recent issue templates (bug_report.md, feature_request.md, other-issue.md). Focus appears to be on code quality and modernization given the 'Ship of Theseus' description and extensive refactoring of a mature codebase.

git clone https://github.com/HMBSbige/ShadowsocksR-Windows.git && cd ShadowsocksR-Windows && powershell -ExecutionPolicy Bypass -File build.ps1 — this runs the PowerShell build script which compiles the C# solution (shadowsocks-csharp.sln) and patches native DLL paths via DotNetDllPathPatcher.ps1.

Daily commands: Open shadowsocks-csharp.sln in Visual Studio 2022 Community and Build → Build Solution, or run powershell build.ps1 from repository root. The compiled executable launches the WinForms UI; local proxy listens on configurable ports (default SOCKS5 on 1080, HTTP on 8118 inferred from typical SSR defaults).

• shadowsocks-csharp/Controller/MainController.cs — Core orchestrator managing proxy state, server selection, and service lifecycle—all features depend on this controller
• shadowsocks-csharp/Model/Configuration.cs — Defines the configuration model and serialization; understanding this is essential for settings, server profiles, and persistence
• shadowsocks-csharp/Encryption/EncryptorFactory.cs — Factory for all encryption implementations (OpenSSL, Sodium, stream ciphers); critical for protocol compatibility and security
• shadowsocks-csharp/Controller/Service/Local.cs — Local proxy listener and SOCKS5 forwarder—the main data path from client to remote server
• shadowsocks-csharp/Controller/SystemProxy.cs — Windows system proxy configuration; essential for transparent operation and network interception setup
• shadowsocks-csharp/Controller/Service/HttpProxyRunner.cs — HTTP/HTTPS proxy implementation wrapping the SOCKS5 backend; required for browser and application compatibility
• shadowsocks-csharp.sln — Visual Studio solution file defining the project structure, build targets, and dependencies for the entire application

Add a new encryption cipher

1. Define the cipher metadata (name, key/IV size, block size) in EncryptorInfo enum or configuration (shadowsocks-csharp/Encryption/EncryptorInfo.cs)
2. Create a new encryptor class inheriting from StreamEncryptor or EncryptorBase, implementing IEncryptor (shadowsocks-csharp/Encryption/Stream/StreamEncryptor.cs)
3. Register the new cipher in EncryptorFactory.CreateEncryptor() with algorithm dispatch logic (shadowsocks-csharp/Encryption/EncryptorFactory.cs)
4. Add unit tests covering encrypt/decrypt round-trip and known test vectors (UnitTest/EncryptionTest.cs)

Add a new proxy mode or rule-based routing

1. Define the new mode enum value in ProxyMode.cs or create a new enum in Enums folder (shadowsocks-csharp/Enums/ProxyMode.cs)
2. Add mode selector property to Configuration model and ensure JSON serialization (shadowsocks-csharp/Model/Configuration.cs)
3. Update SystemProxy.cs to handle Windows registry/settings for the new mode (shadowsocks-csharp/Controller/SystemProxy.cs)
4. Modify Local.cs or create a new Service to implement the routing decision logic at proxy level (shadowsocks-csharp/Controller/Service/Local.cs)
5. Add UI XAML form in I18N/ for users to select and configure the new mode (shadowsocks-csharp/I18N/SettingsWindow.en-US.xaml)

Add a new server subscription format parser

1. Study the existing subscription response format in UpdateNode.cs (shadowsocks-csharp/Controller/HttpRequest/UpdateNode.cs)
2. Extend UpdateSubscribeManager

Native DLL path hardcoding: the build must run DotNetDllPathPatcher.ps1 to patch libsscrypto DLL paths — manual edits to DLL references will break at runtime. Windows-only development: SOCKS5/HTTP services bind to localhost Windows ports; no portable build artifacts without patching. Subscription format is strict (inferred ShadowsocksR URI scheme) — malformed server configs silently fail. PAC file abp.js execution context is sandboxed; custom PAC logic may not work without understanding browser-like JavaScript evaluation. Unit tests in UnitTest/EncryptionTest.cs require all cipher suites to be available via native DLLs or tests fail early.

• SOCKS5 Protocol (RFC 1928) — Local.cs and Socks5Forwarder.cs implement the SOCKS5 server that clients connect to; understanding request/response framing, authentication, and address handling is essential to debugging proxy issues
• Stream Cipher vs AEAD Modes — Encryption/ folder implements both stream ciphers (RC4, Chacha20) and authenticated encryption (AES-GCM); protocol-specific cipher negotiation happens during handshake in Local.cs
• Proxy Auto-Config (PAC) — PACServer.cs serves PAC files (proxy.pac.txt) and abp.js engine allows dynamic routing rules; browser/system-level proxy settings point to this daemon to decide which traffic to proxy
• Protocol Obfuscation — ShadowsocksR's key innovation over vanilla Shadowsocks; the Encryption/ and ProtocolResponseDetector.cs implement obfuscators that disguise proxy traffic as normal HTTP/TLS/other protocols to evade detection
• P/Invoke (Platform Invocation Services) — Encryption/ layer uses P/Invoke to call libsscrypto native DLLs for cryptographic operations; understanding P/Invoke marshaling is critical when modifying cipher implementations or debugging DLL loading failures
• Asynchronous Socket Programming — Local.cs, Socks5Forwarder.cs, and HttpPortForwarder.cs use async/await and BeginReceive/BeginSend patterns to multiplex thousands of concurrent client connections; critical for understanding performance and deadlock potential
• WinForms Dispatcher/UI Thread Affinity — MenuViewController.cs and MainController.cs manage UI updates from background service threads; incorrect thread marshaling causes crashes or frozen UI when proxy events occur

• shadowsocks/shadowsocks-windows — Original Shadowsocks Windows client in C#; this is a fork adding ShadowsocksR protocol extensions (obfuscation, multi-protocol support)
• BreakWa11/ShadowsocksR — The upstream ShadowsocksR project that introduced protocol obfuscation; this Windows implementation extends that specification
• HMBSbige/ShadowsocksR-libev — Companion C library/backend for ShadowsocksR; Windows client may use binaries built from or compatible with this project
• haad/proxychains — Linux equivalent for transparent proxy interception; users familiar with proxychains' transparent mode may understand the architecture patterns here
• tinyproxy/tinyproxy — Lightweight HTTP proxy reference; HttpPortForwarder.cs and HttpProxyRunner.cs implement similar HTTP request relay logic

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 encryption modules

The UnitTest/EncryptionTest.cs exists but the Encryption directory contains multiple complex implementations (StreamEncryptor.cs, StreamOpenSSLEncryptor.cs, StreamSodiumEncryptor.cs, OpenSSL.cs, Sodium.cs) with no visible corresponding test coverage. Given the security-critical nature of encryption in a proxy tool, this deserves dedicated test cases for edge cases, key derivation, and algorithm-specific behavior.

• [ ] Expand UnitTest/EncryptionTest.cs with tests for each encryptor type in shadowsocks-csharp/Encryption/Stream/
• [ ] Add tests for OpenSSL.cs and Sodium.cs wrapper implementations in shadowsocks-csharp/Encryption/
• [ ] Test CircularBuffer implementation in shadowsocks-csharp/Encryption/CircularBuffer/ByteCircularBuffer.cs with boundary conditions
• [ ] Add tests for CryptoException.cs error handling paths in shadowsocks-csharp/Encryption/Exception/

Add integration tests for HTTP proxy and SOCKS5 forwarding services

The Service directory contains critical networking components (HttpProxyRunner.cs, Socks5Forwarder.cs, HttpPortForwarder.cs, Local.cs, Listener.cs) but UnitTest directory lacks any tests for these services. Integration tests validating protocol compliance, connection handling, and error scenarios would significantly improve reliability.

• [ ] Create UnitTest/ServiceIntegrationTest.cs to test local proxy listener startup and shutdown
• [ ] Add tests for Socks5Forwarder.cs connection establishment and protocol handshake
• [ ] Test HttpProxyRunner.cs HTTP request/response forwarding with various payloads
• [ ] Validate ProtocolResponseDetector.cs correctly identifies protocol types

Add CI workflow for code coverage reporting and analysis

.github/workflows/CI.yml exists but there's no coverage reporting step. Adding coverage metrics with a tool like Codecov would help maintain code quality, identify untested code paths (especially important for security-sensitive components), and provide visibility to contributors on which areas need testing.

• [ ] Extend .github/workflows/CI.yml to generate coverage reports during the xUnit test execution step
• [ ] Integrate Codecov or similar service to track coverage trends across commits
• [ ] Set a coverage threshold (e.g., 70%) and fail CI if regression occurs
• [ ] Document coverage expectations in CONTRIBUTING.md for new feature PRs

• Add unit tests for shadowsocks-csharp/Controller/Service/HttpPortForwarder.cs (HTTP forwarding logic) and shadowsocks-csharp/Controller/Service/HostDaemon.cs (hosts file management) — these critical services lack dedicated test coverage in UnitTest/.
• Document the subscription server URI format and parsing logic in CONTRIBUTING.md or a new docs/ folder; UpdateSubscribeManager.cs handles parsing but the schema is undocumented, making it hard for users to debug subscription failures.
• Add integration tests in UnitTest/ that validate end-to-end proxy flow: start Local.cs SOCKS5 server, send a real SOCKS5 request, verify encrypted tunnel and response — currently only unit-level encryption and server config are tested.

• High · Potential Unsafe HTTP Request Handling — shadowsocks-csharp/Controller/HttpRequest/. The HttpRequest module contains components for GfwListUpdater, UpdateChecker, and UpdateNode that perform HTTP requests. Without visible input validation or secure certificate pinning, these could be vulnerable to man-in-the-middle (MITM) attacks, especially when downloading critical updates and subscription data. Fix: Implement certificate pinning for HTTPS requests, validate SSL/TLS certificates properly, use secure protocol versions (TLS 1.2+), and validate all downloaded content cryptographically.
• High · Proxy Configuration Handling Without Input Validation — shadowsocks-csharp/Controller/Service/. Multiple service components (HttpProxyRunner, Socks5Forwarder, PACServer) handle network traffic forwarding and proxy configuration. The absence of visible input sanitization could allow injection attacks through malformed proxy configurations or PAC scripts. Fix: Implement strict input validation for all proxy configuration parameters, sanitize PAC script content, and use allowlisting for protocol handlers.
• High · Encryption Library Dependencies Not Clearly Versioned — shadowsocks-csharp/Data/ and shadowsocks-csharp/Encryption/. The codebase uses OpenSSL and Sodium encryption libraries (libsscrypto.dll, libsscrypto64.dll), but version information and integrity verification mechanisms are not visible. Using outdated or compromised encryption libraries could expose cryptographic weaknesses. Fix: Explicitly document and pin library versions, implement subresource integrity checks for DLL files, regularly update to patched versions, and verify binary signatures.
• Medium · Subscription Update Manager Without Signature Verification — shadowsocks-csharp/Controller/Service/UpdateSubscribeManager.cs. UpdateSubscribeManager automatically downloads and processes subscription data. Without visible cryptographic signature verification, malicious subscriptions could be injected. Fix: Implement GPG signature verification or HMAC validation for subscription updates, use secure update channels, and implement rollback protection.
• Medium · PAC File Generation Without XSS Protection — shadowsocks-csharp/Controller/Service/PACDaemon.cs, shadowsocks-csharp/Controller/Service/PACServer.cs. PACDaemon and PACServer generate and serve PAC files that contain JavaScript. If user-controlled data is injected without proper escaping, this could allow JavaScript injection attacks. Fix: Sanitize all user-controlled input before inserting into PAC scripts, use a PAC templating engine with auto-escaping, and validate PAC syntax before serving.
• Medium · Local Service Binding Without Access Control — shadowsocks-csharp/Controller/Service/Listener.cs, shadowsocks-csharp/Controller/Service/PACServer.cs. Multiple local services (HttpProxyRunner, PACServer, Listener) bind to localhost ports. Without explicit access control verification, local privilege escalation attacks could exploit these services. Fix: Bind only to loopback addresses, implement authentication for local services, use least-privilege access controls, and document expected port usage.
• Medium · Configuration File Handling Without Encryption — shadowsocks-csharp/Controller/FileManager.cs. FileManager handles configuration files that likely contain sensitive proxy credentials and server information. If stored unencrypted, this poses a data exposure risk. Fix: Encrypt sensitive configuration data at rest, use secure file permissions (0600), implement credential masking in logs, and never serialize plaintext credentials.
• Medium · Logging of Potentially Sensitive Data — shadowsocks-csharp/Controller/Logging.cs. The Logging module may capture sensitive information such as IP addresses, server configurations, or traffic patterns without visible redaction mechanisms. Fix: Implement sensitive data redaction in logs, avoid logging credentials or keys, use structured logging with levels, and rotate log files securely.
• Low · Hardcoded Data Files Without Integrity Checks — undefined. The Data directory contains binary files (libsscrypto DLLs) and configuration files (abp.js, 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.