zapret/CLAUDE.MD

CLAUDE.MD - AI Assistant Development Guide for zapret (MacOS Edition)

🎯 Project Overview

zapret is a DPI (Deep Packet Inspection) circumvention tool that has been fully refactored for MacOS with native support for both Intel (x86_64) and Apple Silicon (ARM64) architectures.

Core Purpose

• Bypass DPI-based censorship and network filtering
• Provide transparent HTTP/HTTPS proxy capabilities
• Support both Linux and MacOS (Darwin) systems
• Native MacOS integration with PF (Packet Filter) and launchd

Critical Design Principle

⚠️ IMPORTANT: macOS is NOT BSD! While it shares some BSD heritage, it is a unique hybrid system (XNU kernel = Mach + BSD + Apple components). This project correctly treats Darwin as a distinct platform with its own requirements.

📁 Project Structure

zapret/
├── tpws/              # Transparent proxy WebSocket (main component for MacOS)
├── ip2net/            # IP network tools
├── mdig/              # DNS tools
├── nfq/               # Network filtering queue (limited MacOS support)
├── scripts/           # MacOS-specific utilities
│   ├── macos_arch_detect.sh    # Architecture detection and build management
│   └── test_macos_arch.sh      # Comprehensive system testing
├── init.d/macos/      # launchd service scripts
├── install_macos.sh   # MacOS installation script
├── uninstall_macos.sh # MacOS uninstallation script
├── Makefile           # Enhanced build system with MacOS targets
└── docs/              # Documentation

🏗️ Architecture: MacOS Support

Supported Architectures

1. x86_64 (Intel Macs)

   • Target: x86_64-apple-macos<version>
   • Minimum: macOS 10.8 (Mountain Lion)
   • Recommended: macOS 11.0+ (Big Sur)

2. ARM64 (Apple Silicon: M1, M2, M3+)

   • Target: arm64-apple-macos<version>
   • Minimum: macOS 11.0 (Big Sur)
   • Native ARM64 optimization

3. Universal Binaries

   • Single binary containing both architectures
   • Automatic selection at runtime
   • Best for distribution

MacOS-Specific Components

Build System (Makefile)

# Key variables
DIRS_MAC := tpws ip2net mdig  # MacOS-compatible components
MACOS_TARGET                  # Architecture target (auto-detected)
MACOS_VERSION                 # MacOS version (auto-detected)
IS_MACOS                      # Darwin detection flag

New Makefile Targets for MacOS:

• make mac - Build for current architecture (auto-detected)
• make mac-universal - Build universal binary (both architectures)
• make mac-auto - Auto-detect and build
• make mac-info - Display build information
• make mac-clean - Clean MacOS-specific builds

Architecture Detection Script

Location: scripts/macos_arch_detect.sh

Functions:

• detect - Detect current architecture
• info - Display system information
• check - Verify build readiness
• build - Build for current architecture
• universal - Build universal binary
• version <ver> - Set MacOS version target

Usage:

./scripts/macos_arch_detect.sh detect
./scripts/macos_arch_detect.sh info
./scripts/macos_arch_detect.sh build
./scripts/macos_arch_detect.sh universal

Testing Script

Location: scripts/test_macos_arch.sh

Performs comprehensive system testing:

• System information gathering
• Architecture detection validation
• Build tools verification
• Compilation test
• MacOS-specific feature checks

🔧 Development Workflow for Claude

When Making Changes

1. Architecture Awareness

   • Always test on both x86_64 and ARM64 if possible
   • Use universal binary builds for distribution
   • Respect architecture-specific optimizations

2. MacOS vs BSD vs Linux

   • NEVER assume BSD compatibility
   • ALWAYS use Darwin-specific checks
   • PREFER MacOS-native APIs and tools

3. Build System

   • Modify component Makefiles in tpws/, ip2net/, mdig/
   • Update main Makefile for cross-component changes
   • Test with make mac and make mac-universal

4. Testing Protocol

   # Step 1: Clean build
   make mac-clean
   
   # Step 2: Build current architecture
   make mac
   
   # Step 3: Test functionality
   ./scripts/test_macos_arch.sh
   
   # Step 4: Build universal binary
   make mac-universal
   
   # Step 5: Verify installation
   ./install_macos.sh info
   

Key Files to Modify

For Build System Changes

• Makefile - Main build orchestration
• tpws/Makefile - Transparent proxy build
• ip2net/Makefile - IP tools build
• mdig/Makefile - DNS tools build
• scripts/macos_arch_detect.sh - Architecture management

For Installation Changes

• install_macos.sh - MacOS installer
• uninstall_macos.sh - MacOS uninstaller
• install_bin.sh - Binary installation (cross-platform)

For Service Management

• init.d/macos/zapret - launchd service script
• init.d/macos/zapret.plist - launchd configuration

For Documentation

• CLAUDE.MD - This file (AI development guide)
• TODO - Task tracking
• README_MACOS_FINAL.md - Comprehensive MacOS guide
• docs/MACOS_VS_BSD.md - Critical Darwin vs BSD differences

🔍 Common Tasks for Claude

Task 1: Add Support for New MacOS Version

1. Update version detection in scripts/macos_arch_detect.sh
2. Update MACOS_VERSION variable in Makefile
3. Test build on new version
4. Update documentation

Task 2: Fix Architecture-Specific Bug

1. Identify architecture (x86_64 or ARM64)
2. Reproduce on specific architecture
3. Add architecture-specific fix in component Makefile
4. Test on both architectures
5. Verify universal binary works

Task 3: Add New Component

1. Create component directory
2. Add component Makefile with MacOS targets
3. Update main Makefile DIRS_MAC variable
4. Test with make mac
5. Update documentation

Task 4: Improve Build System

1. Modify relevant Makefile(s)
2. Test incremental builds
3. Test clean builds
4. Test universal binary builds
5. Update make mac-info output

Task 5: Enhance Installation

1. Modify install_macos.sh
2. Test installation process
3. Test uninstallation with uninstall_macos.sh
4. Verify service integration
5. Update documentation

⚠️ Important Constraints

What NOT to Do

❌ Do NOT treat macOS as BSD

• Different system calls
• Different networking stack
• Different firewall (PF with Apple modifications)
• Different service management (launchd, not rc)

❌ Do NOT assume Linux compatibility

• No iptables (use PF instead)
• No systemd (use launchd instead)
• No /proc filesystem
• Different socket behavior

❌ Do NOT ignore architecture differences

• x86_64 and ARM64 have different optimizations
• Endianness may differ in edge cases
• System libraries may vary

❌ Do NOT skip testing

• Always run ./scripts/test_macos_arch.sh
• Always test both architectures when possible
• Always verify installation and uninstallation

Security Considerations

🔒 System Integrity Protection (SIP)

• Some operations require SIP awareness
• Never instruct users to disable SIP permanently
• Prefer SIP-compatible solutions

🔒 Code Signing

• Binaries may need signing for distribution
• Respect notarization requirements
• Document signing requirements

🔒 Permissions

• Use appropriate file ownership (root:wheel)
• Respect privilege separation
• Document permission requirements

📚 Reference Documentation

MacOS-Specific Docs

• README_MACOS_FINAL.md - Complete MacOS guide
• README_MACOS_ENHANCED.md - Enhanced features
• README_MACOS_REFACTORING.md - Technical details
• QUICK_START_MACOS.md - Quick start guide
• docs/MACOS_VS_BSD.md - Darwin vs BSD differences

General Documentation

• docs/readme.en.md - General project documentation
• docs/bsd.en.md - BSD reference (NOT for macOS!)
• CHANGELOG_MACOS_COMPLETE.md - Complete changelog
• CHANGELOG_MACOS_REFACTORING.md - Refactoring details

🛠️ Development Tools

Required Tools (MacOS)

• Xcode Command Line Tools or full Xcode
• clang/LLVM compiler
• make (BSD make is fine)
• git
• sw_vers (system version info)
• uname (architecture detection)

Optional Tools

• Homebrew (for dependencies)
• lldb (debugging)
• Instruments (profiling)

Verification Commands

# Check compiler
clang --version

# Check make
make --version

# Check system
sw_vers
uname -a

# Check architecture
uname -m
arch

# Full system test
./scripts/test_macos_arch.sh

🚀 Quick Start for Development

Initial Setup

# 1. Clone repository (if not already)
git clone <repo-url>
cd zapret

# 2. Verify system
./scripts/macos_arch_detect.sh info

# 3. Test build system
make mac-info

# 4. Build
make mac

# 5. Test
./scripts/test_macos_arch.sh

Making Changes

# 1. Create feature branch
git checkout -b feature/my-macos-feature

# 2. Make changes to code

# 3. Clean build
make mac-clean

# 4. Test build
make mac

# 5. Run tests
./scripts/test_macos_arch.sh

# 6. Build universal (if needed)
make mac-universal

# 7. Commit
git add .
git commit -m "Description of MacOS changes"

# 8. Push
git push -u origin feature/my-macos-feature

📊 Project Status

Completed ✅

• Full x86_64 (Intel) support
• Full ARM64 (Apple Silicon) support
• Universal binary support
• Automatic architecture detection
• Enhanced build system
• MacOS-specific installation
• Service integration (launchd)
• Firewall integration (PF)
• Comprehensive testing tools
• Complete documentation

In Progress 🔄

• See TODO file for current tasks

Future Enhancements 🔮

• macOS 15.0+ support
• Performance benchmarking
• Homebrew package
• Cross-compilation from Linux
• Automated testing framework

💡 Tips for Claude

1. Always Read First: Before modifying any file, read it completely
2. Understand Context: Check related files and documentation
3. Test Thoroughly: Use provided testing scripts
4. Document Changes: Update relevant documentation
5. Consider Architecture: Think about both x86_64 and ARM64
6. Respect MacOS: Don't treat it as Linux or BSD
7. Check TODO: See TODO file for planned work
8. Use Scripts: Leverage scripts/macos_arch_detect.sh and scripts/test_macos_arch.sh
9. Build Incremental: Test changes incrementally
10. Think Security: Consider SIP, permissions, and signing

🔗 Quick Reference

Build Commands

make mac              # Build current arch
make mac-universal    # Build universal
make mac-clean        # Clean MacOS builds
make mac-info         # Show build info
make mac-auto         # Auto build

Script Commands

./scripts/macos_arch_detect.sh detect     # Detect arch
./scripts/macos_arch_detect.sh info       # System info
./scripts/macos_arch_detect.sh check      # Build check
./scripts/macos_arch_detect.sh build      # Build current
./scripts/macos_arch_detect.sh universal  # Build universal
./scripts/test_macos_arch.sh              # Full test

Installation Commands

./install_macos.sh build      # Build only
./install_macos.sh install    # Install only
./install_macos.sh full       # Build + install
./install_macos.sh info       # System info
./uninstall_macos.sh          # Uninstall

Service Commands

sudo /opt/zapret/init.d/macos/zapret start
sudo /opt/zapret/init.d/macos/zapret stop
sudo /opt/zapret/init.d/macos/zapret restart
sudo /opt/zapret/init.d/macos/zapret status

🎯 Goal for Claude

When working on this project, Claude should:

1. Understand the MacOS-specific architecture
2. Respect the differences between macOS, BSD, and Linux
3. Test changes on both architectures when possible
4. Document all changes clearly
5. Maintain backward compatibility
6. Follow MacOS best practices
7. Use provided tools and scripts
8. Keep the TODO file updated
9. Ensure security and permissions are correct
10. Deliver production-ready code

---

Project Type: DPI Circumvention Tool Primary Platform: macOS (Darwin) Secondary Platform: Linux Architectures: x86_64, ARM64, Universal Status: Production Ready ✅ Last Updated: 2025-12-10

Remember: macOS is a unique hybrid system - treat it with the respect it deserves!