h3-guard

Table of Contents

• What is H3-Guard?
• Features
• Installation
• Quick Start
• CLI Usage
• Configuration Guide
• API Reference
• Usage Examples
• FAQ
• Terms of Service
• License

What is H3-Guard?

H3-Guard (The Shield) is a high-performance reverse proxy that sits in front of your backend servers. It handles QUIC/HTTP3 with TLS 1.3, validates JWT or API Key authentication, enforces rate limiting, and forwards clean traffic to your backend. Built with IP shuffling detection that blocks malicious IPs at the kernel level using iptables.

Features

| Category | Features | |----------|----------| | Protocol | QUIC/HTTP3, TLS 1.3 only, HTTP/1.1 fallback | | Authentication | JWT (HS256/RS256), API Key, No-Auth testing mode | | Security | IP shuffling detection, kernel-level blocking, rate limiting per IP | | Performance | Lightweight Node.js, async I/O, connection pooling | | CLI Support | Start proxy, generate tokens, unblock IPs, status check | | Rate Limiting | Per IP or per token, configurable windows, automatic bans | | DDoS Protection | Failed handshake detection, automatic iptables drop rules | | Backend Support | HTTP/1.1, Unix sockets, configurable timeouts | | Logging | Winston logger, file rotation, error tracking |

Installation

From NPM

npm install h3-guard
npm install -g h3-guard

Requirements

Requirement Minimum Recommended Node.js 18.0.0 20.0.0+ OpenSSL 1.1.1 3.0.0+ RAM 256 MB 1 GB+ Storage 50 MB 100 MB OS Linux 5.4+ Ubuntu 22.04+

Generate SSL Certificates

# Self-signed for testing
openssl req -x509 -newkey rsa:4096 -keyout certs/privkey.pem -out certs/fullchain.pem -days 365 -nodes -subj "/CN=localhost"

# Or use Let's Encrypt for production
certbot certonly --standalone -d yourdomain.com

Quick Start

Basic Server with JWT

const { H3GuardServer, CertificateLoader, createAuthStrategy, RateLimiter, BackendForwarder } = require('h3-guard');

async function main() {
  const certLoader = new CertificateLoader('./certs/privkey.pem', './certs/fullchain.pem');
  const authStrategy = createAuthStrategy('jwt', 'your-secret-key', 'Authorization');
  const rateLimiter = new RateLimiter(100, 60000, 10, 300000);
  const backendForwarder = new BackendForwarder('http://127.0.0.1:8080', 5000);
  
  const server = new H3GuardServer(443, '0.0.0.0', certLoader, authStrategy, rateLimiter, backendForwarder);
  await server.start();
  
  console.log('H3-Guard running on port 443');
}

main();

Generate JWT Token

h3-guard token generate --user admin --expiry 30d

Start Proxy with Config File

h3-guard start --config ./config.yaml

CLI Usage

Basic Commands

# Start proxy with config file
h3-guard start --config ./config.yaml

# Start proxy in no-auth mode (testing only)
h3-guard start --port 443 --target http://localhost:8080 --no-auth

# Generate JWT token
h3-guard token generate --user dimzxzzx07 --expiry 30d

# Generate API key
h3-guard token generate --user dimzxzzx07 --api-key

# Unblock an IP address
h3-guard unblock 192.168.1.100

# Check status and statistics
h3-guard status

Command Options

Command Alias Description start -s Start proxy server token generate -t Generate JWT or API key unblock -u Unblock IP from rate limiter status -st Show proxy status --config -c Path to config file --port -p Port to listen on (default: 443) --target -t Backend target URL --no-auth -n Disable authentication (testing only) --debug -d Enable debug logging

Configuration Guide

YAML Configuration (config.yaml)

server:
  port: 443
  host: 0.0.0.0
  certs:
    key: "./certs/privkey.pem"
    cert: "./certs/fullchain.pem"

auth:
  strategy: "jwt"
  secret: "your-super-secret-key-change-this"
  header_name: "Authorization"

rate_limit:
  max_requests: 100
  window_ms: 60000

backend:
  target: "http://127.0.0.1:8080"
  timeout: 5000

JSON Configuration (config.json)

{
  "server": {
    "port": 443,
    "host": "0.0.0.0",
    "certs": {
      "key": "./certs/privkey.pem",
      "cert": "./certs/fullchain.pem"
    }
  },
  "auth": {
    "strategy": "jwt",
    "secret": "your-super-secret-key-change-this",
    "header_name": "Authorization"
  },
  "rate_limit": {
    "max_requests": 100,
    "window_ms": 60000
  },
  "backend": {
    "target": "http://127.0.0.1:8080",
    "timeout": 5000
  }
}

Environment Variables (.env)

LOG_LEVEL=info
DEFAULT_PORT=443
DEFAULT_HOST=0.0.0.0
BACKEND_TIMEOUT=5000
CERT_KEY_PATH=./certs/privkey.pem
CERT_CERT_PATH=./certs/fullchain.pem
JWT_SECRET=your-super-secret-key

API Reference

H3GuardServer Class

const { H3GuardServer } = require('h3-guard');

Constructor

const server = new H3GuardServer(port, host, certLoader, authStrategy, rateLimiter, backendForwarder);

Parameters:

· port (number): Listening port · host (string): Binding address · certLoader (CertificateLoader): SSL certificate loader · authStrategy (AuthStrategy): Authentication strategy · rateLimiter (RateLimiter): Rate limiter instance · backendForwarder (BackendForwarder): Backend forwarder

Methods

Method Description start() Start the proxy server stop() Stop the proxy server

RateLimiter Class

const { RateLimiter } = require('h3-guard');

Constructor

const limiter = new RateLimiter(maxRequests, windowMs, maxFailedHandshakes, banDurationMs);

Parameters:

· maxRequests (number): Maximum requests per window · windowMs (number): Time window in milliseconds · maxFailedHandshakes (number): Failed handshakes before ban · banDurationMs (number): Ban duration in milliseconds

Methods

Method Description recordRequest(ip) Record and check request limit recordFailedHandshake(ip) Record failed handshake isBlocked(ip) Check if IP is blocked unblockIP(ip) Manually unblock IP

TokenGenerator Class

const { TokenGenerator } = require('h3-guard');

Methods

Method Description generateJWT(userId, secret, expiresIn) Generate JWT token generateAPIKey(secret, prefix) Generate API key verifyAPIKey(key, hash, secret) Verify API key

Usage Examples

Production Setup with Nginx Backend

const { H3GuardServer, CertificateLoader, createAuthStrategy, RateLimiter, BackendForwarder } = require('h3-guard');

const certLoader = new CertificateLoader('/etc/letsencrypt/live/domain.com/privkey.pem', '/etc/letsencrypt/live/domain.com/fullchain.pem');
const authStrategy = createAuthStrategy('jwt', process.env.JWT_SECRET, 'Authorization');
const rateLimiter = new RateLimiter(200, 60000, 10, 300000);
const backendForwarder = new BackendForwarder('http://unix:/var/run/nginx.sock:/', 3000);

const server = new H3GuardServer(443, '0.0.0.0', certLoader, authStrategy, rateLimiter, backendForwarder);
server.start();

IP Whitelisting with Custom Logic

class CustomAuthStrategy {
  constructor(allowedIPs) {
    this.name = 'custom';
    this.allowedIPs = allowedIPs;
  }
  
  async authenticate(request) {
    const clientIP = request.connectionId;
    
    if (this.allowedIPs.includes(clientIP)) {
      return { success: true, userId: clientIP };
    }
    
    return { success: false, error: 'IP not whitelisted' };
  }
}

Docker Deployment

FROM node:20-alpine

RUN apk add --no-cache openssl iptables

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 443/udp 443/tcp

CMD ["node", "dist/cli.js", "start", "--config", "./config.yaml"]

FAQ

Q1: How fast is H3-Guard compared to Nginx?

Answer: H3-Guard achieves approximately 80-90% of Nginx performance for HTTP/3 traffic. With Node.js async I/O, it can handle 5,000-10,000 concurrent connections on modern hardware.

Valid Data: Nginx with HTTP/3 does 50-100k RPS. H3-Guard does 8-15k RPS on 4-core CPU. For authentication and rate limiting use cases, this is sufficient for most API gateways.

Q2: Does IP shuffling detection work without root access?

Answer: Without root access, IP blocking happens only at the application level. Kernel-level iptables blocking requires root/sudo. The proxy will still track and reject requests from malicious IPs, but UDP packets will still reach userspace.

Valid Data: Application-level blocking consumes CPU for each packet. Kernel-level blocking drops packets before they reach the application, saving 90%+ CPU during DDoS attacks.

Q3: How many concurrent clients can it handle?

Answer: Performance depends on CPU cores and RAM.

CPU Cores RAM Recommended Clients Maximum Clients 1 core 512 MB 100-500 1,000 2 cores 1 GB 500-2,000 5,000 4 cores 2 GB 2,000-5,000 10,000 8 cores 4 GB 5,000-10,000 25,000

Valid Data: Each idle connection consumes ~50KB RAM. Each active request consumes ~10-50MB during processing. Rate limiting state per IP consumes ~200 bytes.

Q4: Why do I get "Failed to load certificates" error?

Answer: This error occurs when certificate files don't exist or have incorrect permissions.

Solutions:

# Generate test certificates
mkdir -p certs
openssl req -x509 -newkey rsa:4096 -keyout certs/privkey.pem -out certs/fullchain.pem -days 365 -nodes

# Fix permissions
chmod 644 certs/*.pem
chmod 600 certs/privkey.pem

# Verify files exist
ls -la certs/

Valid Data: On Ubuntu 22.04, self-signed certificates work for testing. For production, use Let's Encrypt certificates from /etc/letsencrypt/live/domain/

Q5: Can I use this behind Cloudflare?

Answer: Yes, but Cloudflare already terminates QUIC. Configure Cloudflare to proxy HTTP/1.1 to your origin, or disable Cloudflare QUIC and let the proxy handle it directly.

Valid Data: Cloudflare supports QUIC passthrough on Enterprise plans. For Free/Pro plans, Cloudflare terminates QUIC and forwards as HTTP/1.1. The proxy works in both modes.

Q6: How do I monitor blocked IPs?

Answer: Use built-in logging or iptables monitoring.

Built-in logs:

tail -f proxy-combined.log | grep BLOCKED

IPTables monitoring:

# View active blocks
sudo iptables -L INPUT -n -v | grep DROP

# Monitor packet drops
sudo watch -n 1 'iptables -L INPUT -n -v | grep DROP'

# Count drops per IP
sudo iptables -L INPUT -n -v --line-numbers

Terms of Service

Please read these Terms of Service carefully before using H3-Guard.

1. Acceptance of Terms

By downloading, installing, or using H3-Guard (the "Software"), you agree to be bound by these Terms of Service.

1. Intended Use

H3-Guard is designed for legitimate purposes including:

· Securing your own backend APIs · Protecting internal services from abuse · Adding authentication to legacy applications · Rate limiting public endpoints · DDoS mitigation for your own infrastructure

1. Prohibited Uses

You agree NOT to use H3-Guard for:

· Hiding illegal activities · Bypassing security controls you don't own · Attacking or probing third-party services · Any activity that violates local, state, or federal laws · Circumventing rate limits on services you don't own

1. Responsibility and Liability

THE AUTHOR PROVIDES THIS SOFTWARE "AS IS" WITHOUT WARRANTIES. YOU BEAR FULL RESPONSIBILITY FOR YOUR ACTIONS. THE AUTHOR IS NOT LIABLE FOR ANY DAMAGES, BANS, LEGAL CONSEQUENCES, OR ANY OTHER OUTCOMES RESULTING FROM YOUR USE.

1. Legal Compliance

You agree to comply with all applicable laws in your jurisdiction regarding reverse proxies, authentication systems, and data protection (GDPR, CCPA, etc.).

1. No Warranty

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.

1. Indemnification

You agree to indemnify and hold the Author harmless from any claims arising from your use of the Software.

1. Ethical Reminder

I built H3-Guard to help developers secure their applications and protect their infrastructure. Please use this tool responsibly. Don't use it for attacks, don't use it to bypass others' security, and respect the laws of your country. If you choose to misuse this tool, you alone bear the consequences.

License

MIT License

Copyright (c) 2026 Dimzxzzx07

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.