SpectreProxy

https://github.com/xyzensun/spectreproxy
Admin
SpectreProxy is an advanced intelligent proxy gateway built on Cloudflare Workers and native TCP...
Tokens:5,151
Snippets:27
Trust Score:5.2
Update:10 months ago
Show doc for...
Tokens:
Raw
### DNS Query Handling (DoH/DoT) with Configuration

Source: https://context7.com/xyzensun/spectreproxy/llms.txt

Supports DNS-over-HTTPS (DoH) and DNS-over-TLS (DoT) for private DNS resolution. Examples show how to construct requests for DoH and DoT queries, including custom server configurations. Utilizes specific URL formats and accepts configuration objects.

```javascript
// URL format for DNS queries:
// https://worker.domain.com/{AUTH_TOKEN}/dns/{doh|dot}/{optional_server}

// Example DoH query
// GET https://worker.example.com/token123/dns/doh?name=example.com&type=A
const dohRequest = new Request(
  'https://worker.example.com/token123/dns/doh?name=example.com&type=A',
  {
    method: 'GET',
    headers: { 'Accept': 'application/dns-json' }
  }
);

// Example DoT query
const dotRequest = new Request(
  'https://worker.example.com/token123/dns/dot?name=example.com&type=AAAA',
  {
    method: 'GET',
    headers: { 'Accept': 'application/dns-json' }
  }
);

// Custom DNS server
const customDohRequest = new Request(
  'https://worker.example.com/token123/dns/doh/cloudflare.dns.com'
);

// Configuration for DNS proxies
const dnsConfig = {
  AUTH_TOKEN: 'token123',
  DOH_SERVER_HOSTNAME: 'dns.google',
  DOH_SERVER_PORT: 443,
  DOH_SERVER_PATH: '/dns-query',
  DOT_SERVER_HOSTNAME: 'dns.google',
  DOT_SERVER_PORT: 853
};
```

--------------------------------

### Configure Cloud Provider Proxy Strategy (JavaScript)

Source: https://context7.com/xyzensun/spectreproxy/llms.txt

This JavaScript code configures SpectreProxy to use a 'cloudprovider' proxy strategy, routing traffic through serverless functions on platforms like Vercel or Zeabur. It specifies the URL of the cloud provider function and an authentication token. The example also shows how to instantiate and use the `CloudProviderProxy` class to connect to an HTTP endpoint, internally constructing the proxy URL with the target.

```javascript
// Configure cloud provider proxy
const config = {
  PROXY_STRATEGY: 'cloudprovider',
  CLOUD_PROVIDER_URL: 'https://your-function.vercel.app/api/proxy',
  AUTH_TOKEN: 'token123',
  DEBUG_MODE: false
};

// The cloud provider function receives requests in format:
// https://your-function.vercel.app/api/proxy?target=https://api.example.com/data

// Example usage in SpectreProxy
import { CloudProviderProxy } from './src/proxies/cloud-provider.js';

const proxy = new CloudProviderProxy(config);
const request = new Request('https://api.openai.com/v1/models', {
  method: 'GET',
  headers: { 'Authorization': 'Bearer sk-...' }
});

const response = await proxy.connectHttp(request, 'https://api.openai.com/v1/models');
// Internally calls: https://your-function.vercel.app/api/proxy?target=https://api.openai.com/v1/models
```

--------------------------------

### Deploy Third-Party Proxy on Vercel/Zeabur (JavaScript)

Source: https://context7.com/xyzensun/spectreproxy/llms.txt

This JavaScript code snippet demonstrates how to deploy a third-party HTTP proxy service on platforms like Vercel or Zeabur. It handles incoming requests, extracts the target URL, validates it, and forwards the request to the target while removing sensitive headers. It returns an error if the 'target' parameter is missing or invalid. This is intended for use with SpectreProxy's 'thirdparty' proxy strategy.

```javascript
export default async function handler(request) {
  const { searchParams } = new URL(request.url);
  const targetUrl = searchParams.get('target');

  if (!targetUrl) {
    return new Response('Error: Missing "target" parameter', { status: 400 });
  }

  // Validate URL
  try {
    const url = new URL(targetUrl);
    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
      throw new Error('Invalid protocol');
    }
  } catch (err) {
    return new Response('Error: Invalid target URL', { status: 400 });
  }

  // Forward request, removing revealing headers
  const forwardHeaders = new Headers(request.headers);
  forwardHeaders.delete('host');
  for (const [key] of request.headers.entries()) {
    if (key.toLowerCase().startsWith('cf-') || key.toLowerCase().startsWith('x-forwarded-')) {
      forwardHeaders.delete(key);
    }
  }

  try {
    const response = await fetch(targetUrl, {
      method: request.method,
      headers: forwardHeaders,
      body: request.body,
      redirect: 'manual'
    });
    return response;
  } catch (error) {
    return new Response(`Error: ${error.message}`, { status: 502 });
  }
}

// Configure in SpectreProxy
const config = {
  PROXY_STRATEGY: 'thirdparty',
  THIRD_PARTY_PROXY_URL: 'https://your-proxy.vercel.app/api/proxy',
  AUTH_TOKEN: 'token123'
};
```

--------------------------------

### AI Gateway Configuration and Routing Logic (JavaScript)

Source: https://context7.com/xyzensun/spectreproxy/llms.txt

Configures an AI Gateway with URL presets for common AI services and host-specific routing rules. It supports SOCKS5 fallback and direct fetch methods, managing API authentication tokens and debug modes.

```javascript
// AIGatewayWithSocks.js configuration
const config = {
  AUTH_TOKEN: "your-secret-token",
  DEBUG_MODE: false,
  ENABLE_UA_RANDOMIZATION: true,
  ENABLE_ACCEPT_LANGUAGE_RANDOMIZATION: false,
  ENABLE_SOCKS5_FALLBACK: true
};

// URL preset mapping for common AI services
const URL_PRESETS = new Map([
  ["gemini", "https://generativelanguage.googleapis.com"],
  ["openai", "https://api.openai.com"],
  ["anthropic", "https://api.anthropic.com"],
  ["cohere", "https://api.cohere.ai"]
]);

// Host-specific routing configuration
const HOST_REQUEST_CONFIG = new Map([
  ["api.openai.com", "socks5"],                        // Force SOCKS5
  ["generativelanguage.googleapis.com", "nativeFetch"], // Direct socket
  ["api.anthropic.com", "socks5"]
]);

// Example 1: Using URL preset
// curl https://worker.example.com/your-secret-token/openai/v1/chat/completions \
//   -H "Authorization: Bearer sk-..." \
//   -H "Content-Type: application/json" \
//   -d '{"model":"gpt-4","messages":[{"role":"user","content":"Hello"}]}'

// Example 2: Using full URL
// curl https://worker.example.com/your-secret-token/https://api.openai.com/v1/models \
//   -H "Authorization: Bearer sk-..."

// Example 3: Gemini with preset
// curl https://worker.example.com/your-secret-token/gemini/v1beta/models \
//   -H "x-goog-api-key: YOUR_KEY"

```

--------------------------------

### Cloudflare Worker Entry Point for SpectreProxy (JavaScript)

Source: https://context7.com/xyzensun/spectreproxy/llms.txt

The main entry point for Cloudflare Workers, responsible for handling incoming requests and routing them through the SpectreProxy system. It utilizes the `ShadowProxy` class and requires specific environment variables for configuration.

```javascript
// index.js - Deploy this to Cloudflare Workers
import { ShadowProxy } from './src/main.js';

export default {
  async fetch(request, env, ctx) {
    return await ShadowProxy.handleRequest(request, env, ctx);
  }
};

// Configure environment variables in Cloudflare Workers dashboard:
// AUTH_TOKEN: "your-secret-token-here"
// PROXY_STRATEGY: "socket"
// FALLBACK_PROXY_STRATEGY: "fetch"
// DEBUG_MODE: "false"

// Example request to proxy OpenAI API:
// curl https://your-worker.workers.dev/your-secret-token-here/https://api.openai.com/v1/models \
//   -H "Authorization: Bearer YOUR_OPENAI_KEY"

```

--------------------------------

### SpectreProxy Configuration Manager (JavaScript)

Source: https://context7.com/xyzensun/spectreproxy/llms.txt

Manages environment variables and global configuration settings for SpectreProxy. It provides default configurations and allows updating from environment variables, with utility functions to retrieve specific configuration values.

```javascript
import { ConfigManager } from './src/config.js';

// Default configuration structure
const defaultConfig = ConfigManager.DEFAULT_CONFIG;
// {
//   AUTH_TOKEN: "your-auth-token",
//   DEFAULT_DST_URL: "https://httpbin.org/get",
//   DEBUG_MODE: false,
//   PROXY_STRATEGY: "socket",
//   FALLBACK_PROXY_STRATEGY: "fetch",
//   SOCKS5_ADDRESS: "",
//   THIRD_PARTY_PROXY_URL: "",
//   CLOUD_PROVIDER_URL: "",
//   DOH_SERVER_HOSTNAME: "dns.google",
//   DOH_SERVER_PORT: 443,
//   DOH_SERVER_PATH: "/dns-query",
//   DOT_SERVER_HOSTNAME: "dns.google",
//   DOT_SERVER_PORT: 853
// }

// Update config from environment
const config = ConfigManager.updateConfigFromEnv(env);

// Get specific config value with fallback
const authToken = ConfigManager.getConfigValue(config, 'AUTH_TOKEN', 'default-value');

```

--------------------------------

### SpectreProxy Proxy Factory Pattern (JavaScript)

Source: https://context7.com/xyzensun/spectreproxy/llms.txt

Implements the factory pattern to create various proxy instances based on the specified configuration strategy. It supports multiple strategies like 'socket', 'socks5', and 'doh'.

```javascript
import { ProxyFactory } from './src/proxy-factory.js';
import { ConfigManager } from './src/config.js';

// Create a socket proxy (default)
const config = { PROXY_STRATEGY: 'socket', AUTH_TOKEN: 'token123', DEBUG_MODE: true };
const socketProxy = ProxyFactory.createProxy(config);

// Create SOCKS5 proxy
const socks5Config = {
  PROXY_STRATEGY: 'socks5',
  SOCKS5_ADDRESS: '127.0.0.1:1080',
  AUTH_TOKEN: 'token123'
};
const socks5Proxy = ProxyFactory.createProxy(socks5Config);

// Create DoH (DNS over HTTPS) proxy
const dohConfig = {
  PROXY_STRATEGY: 'doh',
  DOH_SERVER_HOSTNAME: 'dns.google',
  AUTH_TOKEN: 'token123'
};
const dohProxy = ProxyFactory.createProxy(dohConfig);

// Supported strategies: 'socket', 'fetch', 'socks5', 'thirdparty', 'cloudprovider', 'doh', 'dot'

```

--------------------------------

### SOCKS5 Proxy Implementation with Authentication

Source: https://context7.com/xyzensun/spectreproxy/llms.txt

Implements a SOCKS5 proxy that supports both non-authenticated and authenticated connections. It allows establishing HTTP and WebSocket connections through the proxy. Requires 'Socks5Proxy' class.

```javascript
import { Socks5Proxy } from './src/proxies/socks5.js';

// Non-authenticated SOCKS5
const config1 = {
  SOCKS5_ADDRESS: 'proxy.example.com:1080',
  AUTH_TOKEN: 'token123',
  DEBUG_MODE: true
};
const proxy1 = new Socks5Proxy(config1);

// Authenticated SOCKS5 (username:password@host:port)
const config2 = {
  SOCKS5_ADDRESS: 'username:password@proxy.example.com:1080',
  AUTH_TOKEN: 'token123',
  DEBUG_MODE: false
};
const proxy2 = new Socks5Proxy(config2);

// HTTP request through SOCKS5
const request = new Request('https://api.openai.com/v1/models', {
  method: 'GET',
  headers: { 'Authorization': 'Bearer sk-...' }
});

const response = await proxy2.connectHttp(request, 'https://api.openai.com/v1/models');
const models = await response.json();

// WebSocket through SOCKS5
const wsRequest = new Request('wss://stream.example.com', {
  headers: { 'Upgrade': 'websocket' }
});
const wsResponse = await proxy2.connectWebSocket(wsRequest, 'wss://stream.example.com');
```

--------------------------------

### Dynamic SOCKS5 Proxy Fetching and Parsing (JavaScript)

Source: https://context7.com/xyzensun/spectreproxy/llms.txt

Fetches a list of SOCKS5 proxies from multiple API endpoints and randomly selects one. It parses the proxy format (including authentication) for use in network requests.

```javascript
// Configure multiple SOCKS5 API sources
const SOCKS5_API_URLS = [
  "https://api1.example.com/socks5",
  "https://api2.example.com/socks5",
  "https://api3.example.com/socks5"
];

async function parseSocks5Proxy() {
  try {
    // Randomly select an API endpoint
    const randomApiUrl = SOCKS5_API_URLS[Math.floor(Math.random() * SOCKS5_API_URLS.length)];

    // Fetch proxy list
    const response = await fetch(randomApiUrl, { method: 'GET' });
    if (!response.ok) throw new Error(`Failed to fetch: ${response.status}`);

    const proxyData = await response.text();
    const proxyList = proxyData.trim().split('\n').filter(line => line.trim());

    // Randomly select a proxy from the list
    const selectedProxy = proxyList[Math.floor(Math.random() * proxyList.length)];

    // Parse format: [username:password@]host:port or socks5://[username:password@]host:port
    let proxyStr = selectedProxy.trim();
    if (proxyStr.startsWith('socks5://')) proxyStr = proxyStr.substring(9);

    let username = null, password = null, host = null, port = null;
    if (proxyStr.includes('@')) {
      const [authPart, addressPart] = proxyStr.split('@');
      [username, password] = authPart.split(':');
      [host, port] = addressPart.split(':');
    } else {
      [host, port] = proxyStr.split(':');
    }

    return {
      host,
      port: parseInt(port),
      username,
      password,
      hasAuth: !!(username && password)
    };
  } catch (error) {
    throw new Error(`SOCKS5 proxy parsing failed: ${error.message}`);
  }
}

// Usage
const proxy = await parseSocks5Proxy();
// Returns: { host: '1.2.3.4', port: 1080, username: 'user', password: 'pass', hasAuth: true }

```

--------------------------------

### User Agent and Accept-Language Randomization Class (JavaScript)

Source: https://context7.com/xyzensun/spectreproxy/llms.txt

Manages user agent and accept language randomization to maintain device compatibility (mobile/desktop) for stealthy requests. It selects compatible user agents and random accept languages.

```javascript
class UserAgentManager {
  constructor() {
    this.userAgents = [
      'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36...',
      'Mozilla/5.0 (iPhone; CPU iPhone OS 17_3 like Mac OS X)...',
      'Mozilla/5.0 (Windows NT 10.0; Win64; x64)...'
    ];
    this.acceptLanguages = [
      'en-US,en;q=0.9',
      'zh-CN,zh;q=0.9,en;q=0.8',
      'en-GB,en;q=0.9'
    ];
  }

  getCompatibleUserAgent(originalUA) {
    const isMobile = /Android|iPhone|iPad|iPod|Mobile/i.test(originalUA);
    const compatibleAgents = this.userAgents.filter(
      ua => isMobile === /Android|iPhone|iPad|iPod|Mobile/i.test(ua)
    );
    return compatibleAgents[Math.floor(Math.random() * compatibleAgents.length)];
  }
}

// Usage in requests
const uaManager = new UserAgentManager();
const originalUA = 'Mozilla/5.0 (iPhone...)';
const randomUA = uaManager.getCompatibleUserAgent(originalUA);
// Returns a random mobile UA since original was mobile

const randomLang = uaManager.getRandomAcceptLanguage();
// Returns random Accept-Language header

```

--------------------------------

### Request URL Parsing and Routing with ShadowProxy

Source: https://context7.com/xyzensun/spectreproxy/llms.txt

Parses incoming request URLs to extract target URLs and validates authentication tokens. It supports HTTPS proxying and handles different URL formats, falling back to a default destination if the token is invalid. Requires 'ShadowProxy' class.

```javascript
import { ShadowProxy } from './src/main.js';

// URL format: https://worker.domain.com/{AUTH_TOKEN}/{protocol}/{target_path}

// Example 1: HTTPS proxy
// https://worker.example.com/token123/https/api.openai.com/v1/models
const request1 = new Request('https://worker.example.com/token123/https/api.openai.com/v1/models');
const config = { AUTH_TOKEN: 'token123', DEFAULT_DST_URL: 'https://httpbin.org/get' };
const dstUrl1 = ShadowProxy.parseDestinationUrl(request1, config);
// Returns: "https://api.openai.com/v1/models"

// Example 2: Protocol with colon
// https://worker.example.com/token123/https:/api.example.com/data
const request2 = new Request('https://worker.example.com/token123/https:/api.example.com/data');
const dstUrl2 = ShadowProxy.parseDestinationUrl(request2, config);
// Returns: "https://api.example.com/data"

// Example 3: Invalid token returns default
const request3 = new Request('https://worker.example.com/wrong-token/https/api.example.com');
const dstUrl3 = ShadowProxy.parseDestinationUrl(request3, config);
// Returns: "https://httpbin.org/get"

// Example 4: With query parameters
const request4 = new Request('https://worker.example.com/token123/https/api.example.com/search?q=test&limit=10');
const dstUrl4 = ShadowProxy.parseDestinationUrl(request4, config);
// Returns: "https://api.example.com/search?q=test&limit=10"
```

--------------------------------

### SpectreProxy Socket Proxy with Fallback (JavaScript)

Source: https://context7.com/xyzensun/spectreproxy/llms.txt

Provides a direct TCP socket connection for proxying HTTP/HTTPS and WebSocket requests. It includes an automatic fallback mechanism to alternative strategies (e.g., 'fetch') if the primary socket connection fails due to network restrictions.

```javascript
import { SocketProxy } from './src/proxies/socket.js';

const config = {
  AUTH_TOKEN: 'secure-token',
  DEBUG_MODE: false,
  FALLBACK_PROXY_STRATEGY: 'fetch'
};
const proxy = new SocketProxy(config);

// HTTP/HTTPS proxying with automatic fallback
const request = new Request('https://api.example.com/data', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer token123'
  },
  body: JSON.stringify({ query: 'test' })
});

try {
  const response = await proxy.connectHttp(request, 'https://api.example.com/data');
  const data = await response.json();
  console.log(data);
} catch (error) {
  // Automatically falls back to fetch strategy if socket connection fails
  console.error('Proxy error:', error.message);
}

// WebSocket proxying through raw socket
const wsRequest = new Request('wss://stream.example.com/updates', {
  headers: { 'Upgrade': 'websocket' }
});
const wsResponse = await proxy.connectWebSocket(wsRequest, 'wss://stream.example.com/updates');

```
Tokens:
Raw