Codive Relay - Secure Tunneling Server

A production-ready relay server that enables secure remote access to local Codive servers through encrypted WebSocket tunnels. Similar to ngrok, but self-hostable with end-to-end encryption.

Features

Security

• End-to-End Encryption: XChaCha20-Poly1305 encryption with keys shared via URL fragment (never sent to server)
• JWT Authentication: Token-based auth with expiration, claims, and revocation support
• Simple Token Auth: Lightweight alternative for self-hosted deployments
• Auth Rate Limiting: Automatic IP bans after failed authentication attempts
• Security Headers: HSTS, CSP, X-Frame-Options, X-Content-Type-Options on all responses
• Memory Protection: Cryptographic keys are zeroized when dropped

Abuse Prevention

• IP Rate Limiting: Configurable max tunnels per IP address
• Tunnel TTL: Auto-expire tunnels after configurable duration
• Idle Timeout: Close inactive tunnels automatically
• Random IDs Only: Prevent subdomain squatting on public relays

Protocol

• WebSocket-based: Reliable, bidirectional communication
• HTTP Proxying: Full HTTP request/response forwarding
• SSE Streaming: Server-Sent Events pass through correctly
• Keep-Alive: Ping/pong for connection health monitoring
• Automatic Reconnection: Exponential backoff on disconnect

Quick Start

Self-Hosted (Development)

# Terminal 1: Start relay server
cargo run -p codive-relay -- -v

# Terminal 2: Start codive with tunnel
cargo run -p codive-cli -- --serve --tunnel -v

# Terminal 3: Connect as client (use URL from Terminal 2)
cargo run -p codive-cli -- --connect "http://abc123.localhost:3001#<key>"

Production Deployment

# Build release binary
cargo build -p codive-relay --release

# Run with production settings
./target/release/codive-relay \
  --host 0.0.0.0 \
  --port 443 \
  --domain relay.yourdomain.com \
  --https \
  --require-auth \
  --jwt-secret "your-secret-key" \
  -v

Public Relay (Zero-Friction)

For a public relay where users don't need to authenticate:

./target/release/codive-relay \
  --host 0.0.0.0 \
  --domain relay.yourdomain.com \
  --https \
  --random-ids-only \
  --max-tunnel-age 28800 \
  --max-idle-time 1800 \
  --max-tunnels-per-ip 3 \
  -v

Users can then simply run:

codive --serve --tunnel
# Tunnel URL displayed, no auth needed!

CLI Reference

codive-relay [OPTIONS]

Options:
  --host <HOST>                   Host to bind to [default: 127.0.0.1]
  --port <PORT>                   Port to bind to [default: 3001]
  --domain <DOMAIN>               Base domain for tunnel URLs [default: localhost:3001]
  --https                         Use HTTPS for tunnel URLs
  --timeout <SECONDS>             Request timeout [default: 30]

Rate Limiting:
  --max-tunnels-per-ip <N>        Max tunnels per IP [default: 10]
  --max-tunnel-age <SECONDS>      Tunnel TTL (0 = no limit) [default: 0]
  --max-idle-time <SECONDS>       Idle timeout (0 = no limit) [default: 0]
  --random-ids-only               Force random tunnel IDs only

Authentication:
  --require-auth                  Require authentication for connections
  --auth-token <TOKEN>            Valid auth token (can specify multiple)
  --jwt-secret <SECRET>           JWT secret (enables JWT mode)
  --jwt-validity <SECONDS>        JWT token validity [default: 3600]
  --max-auth-failures <N>         Failed attempts before ban [default: 5]
  --auth-ban-duration <SECONDS>   Ban duration [default: 300]

Other:
  -v, --verbose                   Increase verbosity (can repeat)
  -h, --help                      Print help
  -V, --version                   Print version

Architecture

┌─────────────────┐     ┌─────────────────────────┐     ┌──────────────────┐
│  Remote Client  │────▶│     Relay Server        │────▶│  Agent Server    │
│                 │     │  relay.yourdomain.com   │     │  (local machine) │
└─────────────────┘     └─────────────────────────┘     └──────────────────┘
        │                         │                              │
   HTTPS request            Routes by subdomain           WebSocket tunnel
   to tunnel URL            (abc123.relay...)             to local agent
        │                         │                              │
        └─────────────────────────┴──────────────────────────────┘
                    End-to-end encrypted (key in URL fragment)

Crate Structure

• codive-relay: The relay server binary and HTTP/WebSocket handling
• codive-tunnel: Shared library with protocol types, encryption, and wire format

Protocol Flow

1. Agent connects to relay via WebSocket (GET /agent)
2. Agent sends Hello message with optional auth token
3. Relay validates auth, assigns tunnel ID, sends Welcome with tunnel URL
4. Relay forwards HTTP requests to agent as encrypted HttpRequest messages
5. Agent decrypts, forwards to local server, encrypts response
6. Relay returns response to original HTTP client

Configuration Examples

Minimal (Development)

codive-relay

With Authentication

codive-relay \
  --require-auth \
  --auth-token "secret-token-1" \
  --auth-token "secret-token-2"

With JWT

codive-relay \
  --require-auth \
  --jwt-secret "your-256-bit-secret" \
  --jwt-validity 7200

Public Relay (Recommended Settings)

codive-relay \
  --host 0.0.0.0 \
  --domain relay.example.com \
  --https \
  --random-ids-only \
  --max-tunnel-age 28800 \
  --max-idle-time 1800 \
  --max-tunnels-per-ip 3 \
  --max-auth-failures 5 \
  --auth-ban-duration 300

Deployment with Reverse Proxy

Nginx

server {
    listen 443 ssl http2;
    server_name relay.yourdomain.com *.relay.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 86400;
    }
}

Caddy

*.relay.yourdomain.com, relay.yourdomain.com {
    reverse_proxy localhost:3001
}

Docker

FROM rust:1.75 as builder
WORKDIR /app
COPY . .
RUN cargo build -p codive-relay --release

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/target/release/codive-relay /usr/local/bin/
EXPOSE 3001
CMD ["codive-relay", "--host", "0.0.0.0"]

Testing

# Run all tunnel tests
cargo test -p codive-tunnel -p codive-relay

# Run specific test
cargo test -p codive-relay test_jwt_token

# With output
cargo test -p codive-relay -- --nocapture

Current test coverage: 109 tests (47 relay + 62 tunnel)

Future Roadmap

Tier 2: Reliability

• Configurable request timeouts via CLI
• Graceful shutdown with request draining
• Error classification (retryable vs permanent)
• Circuit breaker pattern

Tier 3: Operations

• Prometheus metrics endpoint (/metrics)
• Enhanced health checks with tunnel stats
• Admin API (list tunnels, force disconnect)
• Request/response logging (opt-in)

Tier 4: Features

• WebSocket proxying (bidirectional)
• Custom domain support
• Request inspection UI
• Bandwidth limiting per tunnel

Contributing

Getting Started

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make changes and add tests
4. Run tests: cargo test -p codive-tunnel -p codive-relay
5. Run linter: cargo clippy -p codive-tunnel -p codive-relay
6. Format code: cargo fmt
7. Submit a pull request

Code Structure

crates/
├── codive-tunnel/          # Shared library
│   ├── src/
│   │   ├── lib.rs          # Public exports
│   │   ├── crypto.rs       # XChaCha20-Poly1305 encryption
│   │   └── protocol.rs     # Wire protocol, message types
│   └── Cargo.toml
│
└── codive-relay/           # Relay server
    ├── src/
    │   ├── main.rs         # CLI and server startup
    │   ├── lib.rs          # Router and middleware
    │   ├── state.rs        # Shared state, auth, rate limiting
    │   ├── tunnel.rs       # Tunnel connection management
    │   └── routes/
    │       ├── mod.rs      # Route definitions
    │       ├── agent.rs    # WebSocket handler
    │       └── proxy.rs    # HTTP proxy handler
    └── Cargo.toml

Adding a New Feature

1. Protocol changes: Update codive-tunnel/src/protocol.rs
2. Server logic: Update codive-relay/src/routes/ or state.rs
3. CLI flags: Update codive-relay/src/main.rs
4. Tests: Add to the #[cfg(test)] module in relevant file

Commit Message Format

<type>: <description>

<body>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: <name> <email>

Types: feat, fix, docs, test, refactor, perf

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by ngrok, localtunnel, and Cloudflare Tunnel
• Built with axum, tokio, and chacha20poly1305