𝗖𝗜𝗧𝗔𝗗𝗘𝗟 𝗕𝗥𝗢𝗪𝗦𝗘𝗥

Privacy is not a feature. It's the entire fucking point.

A from-scratch browser engine engineered to obliterate tracking, crush fingerprinting, and restore user sovereignty with extreme technical precision.

⚠️ ALPHA SOFTWARE DISCLAIMER ⚠️

Version: 0.1.0-alpha (Servo Integration Release)

🚨 THIS IS ALPHA SOFTWARE - USE AT YOUR OWN RISK 🚨

• NOT FOR PRODUCTION USE: This software is experimental and under active development
• EXPECT BUGS: Features may not work as expected, crash, or behave unpredictably
• DATA LOSS POSSIBLE: Do not rely on this software for critical browsing or data storage
• SECURITY VULNERABILITIES: Alpha software may contain security flaws - do not use for sensitive activities
• NO WARRANTY: This software is provided "as is" without any warranty of any kind
• BREAKING CHANGES: APIs, features, and functionality may change dramatically between releases
• NOT RESPONSIBLE: We are not responsible if this software causes any issues, including but not limited to:
  • System crashes or instability
  • Data corruption or loss
  • Security breaches
  • Being eaten by a Gru
  • Spontaneous combustion of your computer
  • Temporal paradoxes
  • Existential crises
  • Or any other unforeseen consequences

By using this software, you acknowledge that you understand these risks and use it entirely at your own discretion.

📚 Documentation

For comprehensive documentation about Citadel Browser, please see the docs/ directory:

• Documentation Overview - Complete guide to all documentation
• Release Information - Changelog and release notes
• Architecture & Design - Technical documentation and philosophy
• Development - Contributing guidelines and security practices

Project Status

🎉 ALPHA RELEASE - SERVO INTEGRATION COMPLETE 🎉 The browser now successfully renders real websites with Servo engine integration!

Current Implementation Status

• ✅ Core architecture and component interfaces defined
• ✅ Servo HTML parser integration (Kuchiki-based) - MAJOR MILESTONE
• ✅ Real website rendering capabilities - Now browses sites like example.com
• ✅ 93% test success rate (26/28 tests passing)
• ✅ Basic unit tests for all components
• ✅ Continuous integration and testing infrastructure
• ✅ Vertical tabs implemented and enabled by default
• ✅ Tab bar visibility controls
• ✅ UI customization (theme settings, layout preferences)
• ✅ Privacy-first networking layer with LOCAL_CACHE as default DNS mode
• ✅ Privacy-preserving DNS resolver with local caching
• ✅ HTTPS-only secure connections
• ✅ Privacy-enhancing request headers
• ✅ Tracking parameter removal from URLs
• ✅ Header fingerprint randomization
• ✅ JavaScript engine integration with rquickjs
• ✅ DOM bindings for JavaScript execution
• ✅ Security policies for script execution and CSP compliance
• ✅ JavaScript engine tests with DOM integration (all passing)
• ✅ Production-ready HTML parsing with Servo components
• ✅ Taffy layout engine integration
• 🔄 Enhancing additional privacy and security features
• 🔄 Implementing advanced browsing functionality

Alpha Release Capabilities

✅ What Works:

• Parse and render real HTML from the web
• Navigate to websites (example.com, static sites)
• Privacy-first networking with HTTPS enforcement
• Tab management and UI controls
• JavaScript execution in sandboxed environment
• CSS parsing and basic styling
• DOM manipulation and security filtering

🚧 Known Limitations:

• Complex web applications may have issues
• Some modern web APIs not yet implemented
• Limited multimedia support
• Basic developer tools only

𝗢𝘂𝗿 𝗠𝗶𝘀𝘀𝗶𝗼𝗻

Citadel isn't just a browser engine—it's a declaration of digital human rights. We're built for those who understand that privacy is not a luxury—it's a fundamental necessity.

In an era where users are treated as products and their data harvested without consent, we're taking a scorched-earth approach to browser privacy that makes surveillance capitalism weep.

Open-source. Uncompromising. Zero-tracking. Future-proof.

𝗦𝗲𝗰𝘂𝗿𝗶𝘁𝘆 𝗮𝘀 𝗮 𝗟𝗶𝗳𝗲𝘀𝘁𝘆𝗹𝗲

Privacy isn't just a feature. It's the entire point of our existence.

𝗩𝗮𝗻𝗴𝘂𝗮𝗿𝗱 𝗼𝗳 𝗔𝘂𝘁𝗼𝗻𝗼𝗺𝘆

Zero compromise on user control over their digital experience.

𝗨𝘀𝗲𝗿 𝗦𝗼𝘃𝗲𝗿𝗲𝗶𝗴𝗻𝘁𝘆

Users control their data with no forced third-party dependencies.

𝗣𝗿𝗶𝘃𝗮𝗰𝘆 𝗘𝗻𝗴𝗶𝗻𝗲𝗲𝗿𝗶𝗻𝗴

𝗧𝗿𝗮𝗰𝗸𝗲𝗿 𝗡𝗲𝘂𝘁𝗿𝗮𝗹𝗶𝘇𝗮𝘁𝗶𝗼𝗻

Dynamic blocklists + machine learning detection that annihilates even the most persistent tracking attempts.

𝗔𝗻𝘁𝗶-𝗙𝗶𝗻𝗴𝗲𝗿𝗽𝗿𝗶𝗻𝘁𝗶𝗻𝗴

Canvas fingerprinting prevention, hardware API restriction, and tactical noise injection to mask your digital identity.

𝗛𝗮𝗿𝗱𝗰𝗼𝗿𝗲 𝗦𝗮𝗻𝗱𝗯𝗼𝘅𝗶𝗻𝗴

Per-site process isolation with strict content security policies and cross-site data access prevention.

𝗡𝗲𝘁𝘄𝗼𝗿𝗸 𝗣𝗿𝗶𝘃𝗮𝗰𝘆

User-controlled DNS resolution, minimal HTTP headers, and connection fingerprint randomization.

𝗖𝗼𝗼𝗸𝗶𝗲 𝗖𝗼𝗻𝘁𝗿𝗼𝗹

First-party isolation, automatic expiration, and granular user-controlled storage permissions.

𝗨𝘀𝗲𝗿 𝗦𝗼𝘃𝗲𝗿𝗲𝗶𝗴𝗻𝘁𝘆

Granular privacy controls, transparent data logs, and one-click protection escalation.

𝗔𝗿𝗰𝗵𝗶𝘁𝗲𝗰𝘁𝘂𝗿𝗮𝗹 𝗖𝗼𝗺𝗽𝗼𝗻𝗲𝗻𝘁𝘀

Citadel is built with these core components, all implemented with Rust's strong encapsulation features:

𝗣𝗮𝗿𝘀𝗲𝗿 𝗟𝗮𝘆𝗲𝗿 ✅

• Servo Integration: Production-ready HTML parsing using Kuchiki (Servo-based)
• HTML5ever Backend: Robust HTML5 parsing with proper TreeSink implementation
• Security-Preserving: All parsing maintains Citadel's privacy and security guarantees
• Real Website Support: Successfully parses and renders actual web content
• Attack surface minimization through careful API implementation and selective standard support
• Security-first input handling designed to fail closed rather than open when encountering edge cases

𝗝𝗮𝘃𝗮𝗦𝗰𝗿𝗶𝗽𝘁 𝗘𝗻𝗴𝗶𝗻𝗲 ✅

• Integrated rquickjs engine with hardcore sandbox environment and surgically removed tracking APIs
• DOM bindings implemented with security policies and CSP compliance enforcement
• Privacy-preserving execution with zero external data transmission capabilities for scripts
• Comprehensive test suite with DOM integration and security validation (all tests passing)
• Performance-optimized execution that doesn't sacrifice security for convenience

𝗡𝗲𝘁𝘄𝗼𝗿𝗸𝗶𝗻𝗴 𝗟𝗮𝘆𝗲𝗿

• User-controlled DNS resolution with local cache by default and no reliance on third-party DNS services
• HTTPS-or-die approach that defaults to secure connections and hardens TLS implementation
• Connection fingerprint randomization to prevent server-side tracking and correlation
• Real-world tested: Successfully fetches and renders content from live websites

𝗨𝘀𝗲𝗿 𝗜𝗻𝘁𝗲𝗿𝗳𝗮𝗰𝗲

• Granular privacy controls that give users complete visibility and authority over their data
• Transparent data transmission logs showing exactly what information websites are attempting to access
• Vertical tabs by default for improved usability and efficient screen space utilization
• Alpha-grade UI with basic browsing functionality

Networking Features

The networking layer is the foundation of Citadel's privacy-preserving architecture:

Privacy-First DNS

• Local Cache by Default: Minimize network requests that could be tracked
• No Third-Party DNS Services: We never use external DNS services without your explicit consent
• Optional Secure DNS: Support for DNS over HTTPS (DoH) and DNS over TLS (DoT) as user options
• Normalized TTLs: Prevent timing-based tracking through DNS

Secure Connections

• HTTPS Only: All connections must use HTTPS for privacy and security
• Strict TLS: Modern, secure TLS configurations
• Certificate Validation: Thorough certificate checking
• Connection Security Levels: Configure security vs. compatibility
• Real-World Tested: Successfully connecting to and rendering actual websites

Privacy-Enhanced Requests

• Header Management: Remove or normalize headers that could be used for tracking
• Fingerprint Randomization: Prevent browser fingerprinting through request headers
• User-Agent Control: Randomize or normalize your User-Agent
• URL Cleaning: Automatically strip tracking parameters from URLs
• Privacy Levels: Configure maximum, high, or balanced privacy settings

UI Features

• Tab Management
  • Vertical Tabs: Enabled by default for better screen utilization and improved tab visibility
  • Tab Bar Visibility: Toggle tab bar on/off with Ctrl+H
  • Tab Layout: Switch between vertical and horizontal tabs with Ctrl+Shift+V
  • Theme Support: Choose between light, dark, or system theme

Privacy & Security Features

Key Privacy Principles

• User Sovereignty: All privacy decisions are in your hands
• No Third-Party Dependencies: Local cache for DNS by default - no data sent to third-party DNS providers
• Zero Tracking: No fingerprinting, no tracking, no exceptions
• Alpha-Grade Security: Core security features implemented and tested (93% test pass rate)

Design Patterns

Rust Module Architecture

All major components in Citadel use Rust's powerful module system, which provides:

• Improved Encapsulation: Implementation details are hidden from the public interface
• Memory Safety: Rust's ownership system eliminates entire classes of bugs
• Fearless Concurrency: Safe concurrent code without data races
• Zero-Cost Abstractions: High-level concepts without runtime overhead
• Cleaner Code Organization: Clear separation between interface and implementation

Getting Started

Platform Support

Citadel Browser is primarily designed for macOS, with limited Linux support for unit testing and development purposes.

• macOS: Primary platform with full feature support
• Linux: Limited support for development and testing only

Prerequisites

• Rust and Cargo (latest stable)
• macOS 11.0+ (Big Sur or newer)
• Xcode Command Line Tools
• For Linux development/testing only:
  • pkg-config
  • OpenSSL dev packages
  • Fontconfig dev packages

Building from Source

git clone https://github.com/citadel-browser/citadel-browser-rust.git
cd citadel-browser-rust
cargo build

Running Tests

cargo test
# Expected: 26/28 tests passing (93% success rate)

Running Examples

# Test HTML parsing with Servo integration
cargo run --example html_parse_test

# Test full pipeline including networking and rendering
cargo run --example full_pipeline_test

Basic Usage

# Run the browser with basic website
cargo run -- --url https://example.com

Project Structure

citadel-browser-rust/
├── Cargo.toml             # Workspace configuration
├── crates/                # Rust crates
│   ├── networking/        # Privacy-preserving networking components
│   │   ├── src/           # Source code
│   │   │   ├── dns.rs     # Privacy-focused DNS resolver
│   │   │   ├── request.rs # Privacy-enhancing HTTP requests
│   │   │   ├── response.rs # HTTP response handling
│   │   │   ├── connection.rs # Secure connection management
│   │   │   ├── resource.rs # Resource fetching
│   │   │   ├── error.rs   # Error handling
│   │   │   └── lib.rs     # Library entry point
│   │   ├── examples/      # Usage examples
│   │   └── tests/         # Integration tests
│   ├── parser/            # HTML/CSS/JS parsing components with integrated JS engine
│   │   ├── src/           # Source code
│   │   │   ├── html/      # Servo-integrated HTML parsing
│   │   │   │   ├── mod.rs     # Main HTML parsing module
│   │   │   │   └── converter.rs # Kuchiki to Citadel DOM conversion
│   │   │   ├── js/        # JavaScript engine integration (rquickjs)
│   │   ├── examples/      # HTML parsing tests and demos
│   │   └── tests/         # Parser tests
│   ├── privacy/           # (Coming soon) Privacy enhancement system
│   ├── security/          # (Coming soon) Security enforcement system
│   └── ui/                # (Coming soon) User interface components
├── examples/              # Integration examples and tests
│   ├── html_parse_test.rs      # Basic HTML parsing test
│   └── full_pipeline_test.rs   # Complete pipeline demonstration
└── tests/                 # Integration tests

𝗥𝗼𝗮𝗱𝗺𝗮𝗽

✅ 1. Alpha Stage (CURRENT - VERSION 0.1.0)

✅ COMPLETE: Core engine implementation with fundamental privacy protections:

• ✅ Servo HTML parser integration with Kuchiki
• ✅ Real website rendering capabilities
• ✅ Parser and JavaScript engine with tracking API removal
• ✅ Basic networking layer with HTTPS enforcement
• ✅ Initial fingerprinting protection implementation
• ✅ 93% test success rate
• ✅ Production-ready HTML parsing

2. Beta Stage (Next Major Release)

Enhanced protection and performance improvements:

• Machine learning tracker detection
• Advanced fingerprinting countermeasures
• User interface with privacy controls and real-time tracking visualization
• Enhanced multimedia support
• Web developer tools

3. Release Stage

Fully-featured browser with comprehensive privacy protection:

• Complete engine integration with all privacy modules
• Cross-platform support (desktop and mobile)
• Extension API with strict privacy requirements
• Advanced web standards support

4. Future Expansion

Beyond the horizon:

• Advanced threat intelligence integration
• Privacy-preserving cloud syncing (optional)
• Enhanced OS integration with system-wide privacy controls

𝗝𝗼𝗶𝗻 𝘁𝗵𝗲 𝗣𝗿𝗶𝘃𝗮𝗰𝘆 𝗥𝗲𝘃𝗼𝗹𝘂𝘁𝗶𝗼𝗻

Citadel is currently in alpha with real browsing capabilities. Help us build a more private, more secure web experience for everyone.

Contributing

We welcome contributions that align with our vision of uncompromising privacy and security. Please read docs/development/CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License

Acknowledgments

Inspired by those who believe in digital autonomy and the right to privacy in an increasingly surveilled digital landscape.

Special thanks to the Servo team for their groundbreaking work on web browser engine components that power our HTML parsing capabilities.

See docs/design/DESIGN.md for comprehensive information about project architecture and philosophy.

---

© 2025 Citadel Browser. Open-source. Uncompromising. Zero-tracking.

Testing & Security

Security-First Development

Citadel is built with a security-first mindset. We use several approaches to ensure our code is robust:

Comprehensive Testing

# Run the standard test suite
cargo test

# Run integration tests
cargo test --test '*'

# Current results: 26/28 tests passing (93% success rate)

Example Testing

# Test Servo HTML parsing integration
cargo run --example html_parse_test

# Test full pipeline with networking
cargo run --example full_pipeline_test

Continuous Fuzzing

We employ aggressive fuzzing to discover and fix security issues before they reach production:

# Switch to nightly Rust (required for fuzzing)
rustup default nightly

# Install LLVM tools component
rustup component add llvm-tools-preview

# Install cargo-fuzz (required for fuzzing)
cargo install cargo-fuzz

# Generate corpus for more effective fuzzing
./fuzz/scripts/generate_corpus.sh

# Run all fuzzers with enhanced memory checking
./fuzz/scripts/run_all_fuzzers.sh

# Or run individual fuzzers with dictionaries
cd fuzz && cargo fuzz run dns_resolver corpus/dns_resolver -dict=dictionaries/dns.dict

Each fuzzer uses dictionaries and corpus files specifically designed to test edge cases and potential security vulnerabilities. Our CI automatically runs these fuzzers on every commit to ensure continuous security testing.

See docs/development/FUZZING.md for our complete fuzzing strategy and details on how to contribute to our security efforts.

Any fuzzing failures are considered critical build failures and must be addressed immediately to maintain our security standards.