Trust Proxy Configuration

XyPriss provides advanced trust proxy functionality for modern deployment scenarios including containers, load balancers, and cloud environments. This determines how the server handles X-Forwarded-* headers.

IP Detection

Correctly identify the original client IP instead of the load balancer's IP address.

Protocol Accuracy

Accurately detect if the request was made over HTTP or HTTPS through the proxy chain.

Supported Configuration Types

XyPriss supports several ways to define trusted proxies, from simple booleans to custom validation functions.

1. Boolean & Predefined Ranges

typescript

// Trust all proxies (⚠️ Caution) / Don't trust any (Default)
trustProxy: true; 
trustProxy: false;

// Predefined Scenarios
trustProxy: "loopback"; // 127.0.0.0/8, ::1/128
trustProxy: "uniquelocal"; // 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16

2. CIDR and Exact IPs

typescript

// Trust specific IP addresses or ranges
trustProxy: [
    "203.0.113.10",    // Exact IP
    "10.0.0.0/8",      // CIDR range
    "fc00::/7"         // IPv6 range
];

Deployment Examples

Kubernetes / Docker

typescript

const app = createServer({
    server: {
        trustProxy: ["10.244.0.0/16", "10.96.0.0/12", "loopback"],
    },
});

Production with Load Balancer

typescript

const app = createServer({
    server: {
        trustProxy: ["203.0.113.10", "203.0.113.11", "loopback"],
    },
});

Request API

When trust proxy is enabled, the following request properties are automatically populated using the validated proxy chain:

typescript

app.get("/info", (req, res) => {
    res.json({
        ip: req.ip,             // Resolved Client IP
        ips: req.ips,           // Array of proxy hops
        protocol: req.protocol, // 'http' or 'https'
        secure: req.secure,     // true if connection is secure
    });
});

IP Spoofing Risk

Only trust proxies that you explicitly control. Trusting untrusted proxies allows attackers to spoof their IP address by sending custom X-Forwarded-For headers.

Honeypot & Tarpit

Deflect and slow down automated attacks using deceptive security measures.