Xshield: HTTP Split-Channel Reverse Proxy

Executive Summary

Xshield is a transparent reverse proxy that splits HTTP payloads across N independent HTTPS channels using XorIDA threshold secret sharing. Information-theoretic security: any attacker who compromises K-1 channels learns zero information about the original payload.

Two core functions cover all use cases: splitRequest() takes an HTTP payload and a proxy configuration, splits the payload into N XorIDA shares, wraps each in an Xformat binary envelope, and returns them for transmission across separate channels. reconstructResponse() takes K or more shares, deserializes the envelopes, verifies HMAC integrity, reconstructs the original payload, and returns it. The proxy runs transparently — client and upstream server see only standard HTTPS.

Each channel is defined by a URL, a DID (Decentralized Identifier) for mutual authentication, and an optional provider label and routing priority. Channels can span different cloud providers, geographic regions, or ISPs — the more diverse the network paths, the stronger the security posture.

Zero npm runtime dependencies. Uses only Web Crypto API (HMAC-SHA256, AES-256-GCM) and XorIDA from @private.me/crypto. Works in Node.js, Deno, Bun, Cloudflare Workers, and browsers.

The Problem: Network-Level Adversaries

Standard HTTPS protects payload confidentiality against passive eavesdroppers. But network operators, ISPs, CDNs, and compromised intermediaries can still observe which servers you talk to, how much data you send, and timing patterns. End-to-end encryption stops at the TLS layer — the application payload is encrypted, but a network observer sees the full request/response flow on a single path.

Xshield addresses this by splitting payloads across independent network paths. With a 2-of-3 configuration, an adversary must compromise all three network providers simultaneously to reconstruct even one message. With higher K values, the security grows exponentially: in a 2-of-7 setup, an attacker needs to compromise 7 different organizations at the same time to learn anything.

Threat Model

In scope: Network-level adversaries who control one or more channel paths. An ISP, CDN operator, or cloud provider who observes traffic on their network. A nation-state actor who can intercept HTTPS traffic between client and relays.

Out of scope: Adversaries who control the client itself, the upstream server, or can launch timing/traffic analysis attacks across all channels simultaneously. Xshield is a network-level defense, not a local security boundary.

Architecture

Xshield splits HTTP payloads using XorIDA, routes shares across independent channels, and reconstructs on the other side. The entire flow is transparent to client and upstream server — they see only standard HTTPS.

XorIDA Splitting

Payloads are split using XorIDA (XOR-based Information Dispersal Algorithm) over GF(2). XorIDA produces N shares such that any K shares can reconstruct the original, but K-1 shares reveal nothing.

The splitting process:

1. Pad payload to block boundary (nextOddPrime(n) - 1)
2. Compute HMAC-SHA256 over padded payload
3. Split padded data into N XorIDA shares
4. Generate transaction UUID
5. Wrap each share: [HMAC_KEY:32][HMAC_SIG:32][SHARE_DATA]
6. Serialize envelope (Xformat binary) for each share
7. Return shares + channel assignments

Each share is wrapped in an Xformat binary envelope containing:

• Product type (XSHIELD): Prevents confusion with other envelope types.
• N, K values: Stored with each share for verification.
• Share ID (1-based): Used to index the share during reconstruction.
• Transaction UUID: Links all shares of a single split operation.
• HMAC key + signature + payload: The envelope payload contains the HMAC key, HMAC signature, and the XorIDA share data.

Multi-Channel Routing

Each channel is defined by:

interface ChannelEndpoint {
  channelId: 'aws' | 'azure' | 'gcp'
  url: 'https://relay-1.example.com/share'
  did: 'did:key:z6Mk...'
  provider?: 'AWS us-east-1'
  priority?: 0 // lower = preferred
}

The proxy maintains N channel endpoints. When splitting a payload:

• Share 0 → channels[0].url via POST with HMAC authentication
• Share 1 → channels[1].url (independent network path)
• Share i → channels[i].url

No single channel carries the full payload — each relay holds only one binary share. Even if all N relays are on the same ISP, they operate independently. A network observer on that ISP cannot correlate the three shares without breaking HMAC and deserialization.

DID Mutual Authentication

Each channel endpoint has a DID (Decentralized Identifier) for mutual authentication. Before transmitting a share, the proxy verifies the relay's DID signature. The relay verifies the proxy's DID signature. This prevents relay impersonation and replay attacks.

The authentication flow:

• Proxy constructs a signed message (via Xlink) containing the share and transaction metadata.
• Relay verifies the proxy's signature using the proxy's DID public key.
• Relay responds with its own signed confirmation.
• Proxy verifies relay's signature using the relay's configured DID.

Use Cases

Xshield is designed for deployments where network-level adversaries are a credible threat.

Integration Guide

Xshield is designed for transparent integration. Client and upstream server require zero code changes.

Quick Start

import { splitRequest } from '@private.me/httpsplit';

const config = {
  n: 3,
  k: 2,
  proxyDid: 'did:key:z6MkProxy...',
  channels: [
    { channelId: 'aws', url: 'https://relay-1.com/share', did: 'did:key:z6Mk1...' },
    { channelId: 'azure', url: 'https://relay-2.com/share', did: 'did:key:z6Mk2...' },
    { channelId: 'gcp', url: 'https://relay-3.com/share', did: 'did:key:z6Mk3...' },
  ],
};

const payload = new TextEncoder().encode('{"secret":"data"}');
const result = await splitRequest(payload, config);

if (result.ok) {
  const { shares, transactionId } = result.value;
  // Send each share to its assigned channel relay
  for (let i = 0; i < shares.length; i++) {
    await fetch(config.channels[i].url, {
      method: 'POST',
      body: shares[i],
      headers: { 'X-Transaction-ID': transactionId }
    });
  }
}

Reconstruction

import { reconstructResponse } from '@private.me/httpsplit';

const receivedShares = [share1, share2, share3]; // Uint8Array[]
const result = await reconstructResponse(receivedShares);

if (result.ok) {
  const original = result.value.payload;
  const txId = result.value.transactionId;
  console.log('Reconstructed:', new TextDecoder().decode(original));
} else {
  console.error('Reconstruction failed:', result.error);
}

Proxy Lifecycle

import { createProxy } from '@private.me/httpsplit';

const proxyResult = createProxy(config);

if (proxyResult.ok) {
  const proxy = proxyResult.value;

  // Start the proxy
  await proxy.start();
  console.log(proxy.state); // 'RUNNING'

  // Process requests...

  // Stop the proxy
  await proxy.stop();
  console.log(proxy.state); // 'IDLE'
} else {
  console.error('Invalid config:', proxyResult.error);
}

API Surface

Xshield exports four core functions and several type definitions. All functions return Result<T, ProxyError> — errors are values, not exceptions.

Core Functions

Type Definitions

interface ProxyConfig {
  n: number;                 // Total channels (2–255)
  k: number;                 // Reconstruction threshold (2–n)
  channels: ChannelEndpoint[];
  proxyDid: string;          // DID for mutual auth
  maxPayloadBytes?: number;     // Default: 10 MB
  channelTimeoutMs?: number;   // Default: 30000
  verifyHmac?: boolean;        // Default: true
}

interface SplitResult {
  transactionId: string;
  shares: Uint8Array[];
  channels: ChannelEndpoint[];
  n: number;
  k: number;
}

interface ReconstructResult {
  transactionId: string;
  payload: Uint8Array;
  sharesUsed: number;
}

Security Design

Xshield is built on three cryptographic layers: information-theoretic splitting (XorIDA), transport encryption (AES-256-GCM), and payload integrity (HMAC-SHA256).

Layer 1: Information-Theoretic Security (XorIDA)

Property: K-1 shares reveal zero information about the original payload. This holds regardless of computational power.

Guarantee: In a 2-of-3 split, an attacker who steals 2 shares and breaks HMAC can still only access the payload IF they have a third share. No brute force, no quantum advantage.

Tradeoff: If an attacker gets K shares from K different channels, they reconstruct the plaintext immediately (after HMAC verification). Xshield relies on channel independence — channels must traverse different networks.

Layer 2: Transport Encryption (Per-Channel AES-256-GCM)

Each share is wrapped in an Xformat envelope that includes AES-256-GCM encryption. Even if a channel relay is compromised, the share data is encrypted at rest and in transit.

Key derivation: Envelope encryption key is derived from the proxy DID via HKDF. Channel relays decrypt using their own DID keys.

Layer 3: Payload Integrity (HMAC-SHA256)

HMAC is computed over the PADDED payload (before splitting). The HMAC key and signature are embedded in each share's envelope payload.

Verification: Before XorIDA reconstruction, all K shares are HMAC-verified. If any share is tampered with, reconstruction fails immediately.

Placement: HMAC verification happens BEFORE unpadding. This prevents padding oracle attacks.

Threat Mitigations

Performance Characteristics

Xshield splits and reconstructs at microsecond latencies. Network latency dominates — transmitting shares across N channels and waiting for all to arrive is the bottleneck, not crypto.

Splitting Overhead

Reconstruction Overhead

Reconstruction is marginally slower than splitting because it must wait for K shares to arrive and verify HMAC across all. Typical end-to-end latency (split → transmit → reconstruct):

• LAN (same datacenter): ~15–30 ms (network roundtrip dominates)
• WAN (multi-region): ~80–200 ms (fastest + slowest channel = latency)
• Geo-distributed (3 continents): ~300–500 ms

Known Limitations

Xshield is powerful but has boundaries. Understanding these limitations is critical for correct deployment.

Channel Endpoint Trust

The proxy trusts channel relays to forward shares faithfully and respond honestly. A malicious relay can:

• Drop shares → Reconstruction fails if fewer than K shares arrive
• Delay shares → Reconstruction latency increases
• Tamper with shares → HMAC verification detects tampering (if HMAC is enabled)

Mitigation: Use DID mutual authentication. Monitor relay behavior for consistent drops or delays. Use redundant channels (N > 2K).

No Channel Rotation

Channel endpoints are fixed at proxy creation time. To change channels, the proxy must be stopped and recreated. There is no built-in mechanism to rotate channels during a session.

Mitigation: Plan channel infrastructure carefully. Use provider-agnostic URLs and DID pairs that can be updated out-of-band.

Header Visibility

HTTP headers are encrypted alongside share data. If channel-level encryption is compromised (e.g., relay SSL cert is stolen), headers are exposed.

Mitigation: Use per-channel AES-256-GCM envelope encryption (enabled by default). Assume channels are independent and not on the same ISP.

No Request-Response Binding

Request and response splits use independent UUIDs. An attacker with visibility to all channels could theoretically correlate timing, but would need sophisticated traffic analysis across all N paths.

Mitigation: Use channel path diversity. The more independent the networks, the harder timing correlation becomes.

Payload Size Limits

Default maxPayloadBytes is 10 MB. Larger payloads are rejected to prevent resource exhaustion. Can be configured per proxy instance.

Post-Quantum Security

Xshield inherits post-quantum protection from the PRIVATE.ME platform stack.

Payload Layer (XorIDA)

Status: Quantum-safe unconditionally. XorIDA provides information-theoretic security. K-1 shares reveal zero information regardless of computing power, including quantum computers. No assumption about hardness of any problem.

Transport Layer (Xlink Envelopes)

When messages are exchanged via @private.me/agent-sdk, hybrid post-quantum cryptography protects the envelope:

• Key exchange: X25519 + ML-KEM-768 (FIPS 203) — always-on in v2+ envelopes
• Signatures: Ed25519 + ML-DSA-65 (FIPS 204) — opt-in via postQuantumSig: true

Recommendation

Applications integrating Xshield should create agents with postQuantumSig: true for full post-quantum protection across all three cryptographic layers:

1. Payload layer: XorIDA (information-theoretic)
2. Channel authentication: ML-DSA-65 signatures
3. Transport encryption: ML-KEM-768 key exchange

Error Handling

All Xshield operations return Result<T, ProxyError>. Errors are values, not exceptions. This enables structured error handling and recovery.

Error Categories

Error Handling Pattern

const result = await splitRequest(payload, config);

if (!result.ok) {
  switch (result.error) {
    case 'PAYLOAD_TOO_LARGE':
      console.error('Payload exceeds limit. Chunk it.');
      break;
    case 'INVALID_CONFIG:K_EXCEEDS_N':
      console.error('Config error: k must be <= n');
      break;
    default:
      console.error('Unknown error:', result.error);
  }
}

Codebase Statistics

Xshield is lean and focused. Small surface area, comprehensive testing.

File Breakdown

Testing Coverage

• Configuration validation: All 8 error paths tested
• Splitting: Payload sizes 10 B–10 MB, various N/K combinations
• Reconstruction: Happy path, insufficient shares, HMAC failures, envelope deserialization errors
• Abuse cases: Oversized payloads, duplicate share IDs, UUID mismatches, product type mismatches
• Edge cases: Empty payloads, N=255, large N with large K, padding edge cases