TrustGate Client

A browser-based bot detection library that wraps HTTP clients and collects fingerprinting data to help identify and prevent bot traffic.

Features

• 🔍 Environment Fingerprinting: Collects browser environment data (User-Agent, languages, timezone, screen resolution, etc.)
• 🖼️ Visual Fingerprinting: Canvas, WebGL, and AudioContext fingerprinting
• 🛜 Network Information: Connection type, downlink, RTT
• 🧪 Automation Detection: Detects headless browsers and automation tools
• 🔐 Persistence Checking: Verifies cookies, localStorage, sessionStorage, and indexedDB support
• 🔄 HTTP Client Wrapper: Wraps existing HTTP clients or provides a simple built-in client

Installation

npm install trustgate-client

Development

CI/CD

This project uses GitHub Actions for continuous integration and continuous delivery. The workflow automatically runs unit tests and builds the project on every push to the main branch and on pull requests.

Usage

Basic Usage

import { TrustGateClient } from 'trustgate-client';

// Create a new client with default options
const botDetection = new TrustGateClient();

// Collect bot detection data
const data = botDetection.collectData();
console.log(data);

Wrapping an Existing HTTP Client

import axios from 'axios';
import { TrustGateClient } from 'trustgate-client';

// Create a new client that wraps axios
const botDetection = new TrustGateClient({
  httpClient: axios,
  appendTo: 'headers' // Add data to request headers (default)
});

// Now use axios as normal, bot detection data will be automatically added
// Using async/await
const fetchData = async () => {
  try {
    const response = await axios.get('https://api.example.com/data');
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
};

fetchData();

Using the Built-in HTTP Client

import { TrustGateClient } from 'trustgate-client';

// Create a new client
const botDetection = new TrustGateClient({
  appendTo: 'body' // Add data to request body instead of headers
});

// Create a simple HTTP client with bot detection
const httpClient = botDetection.createHttpClient();

// Use the HTTP client with async/await
const fetchData = async () => {
  try {
    const response = await httpClient.get('https://api.example.com/data');
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
};

fetchData();

Configuration Options

import { TrustGateClient } from 'trustgate-client';

const botDetection = new TrustGateClient({
  // Where to append the collected data ('headers' or 'body')
  appendTo: 'headers',

  // HTTP client to wrap (optional)
  httpClient: null,

  // Enable/disable specific collectors
  collectEnvironment: true,
  collectVisualFingerprint: true,
  collectNetworkInfo: true,
  detectAutomation: true,
  checkPersistence: true
});

Collected Data

The library collects the following data:

Environment Data

• User-Agent (browser, operating system)
• Languages (navigator.language, navigator.languages)
• Timezone and offset
• Screen resolution and window size
• Color depth
• Plugins installed
• Browser feature support

Visual Fingerprinting

• Canvas fingerprinting (rendering text, shapes, colors)
• WebGL fingerprinting (vendor, renderer, version, extensions)
• AudioContext fingerprinting (sample rate, channel count)

Network Information

• Connection type, effective type, downlink, RTT

Automation Detection

• navigator.webdriver check
• Chrome headless detection
• Automation tool properties (Puppeteer, Playwright, etc.)
• Inconsistency detection (resolution, timezone, etc.)

Persistence Checks

• Cookies enabled
• LocalStorage/SessionStorage/IndexedDB support

TypeScript Support

This library includes full TypeScript support with type definitions. You can use it in your TypeScript projects as follows:

Basic TypeScript Usage

import { TrustGateClient, TrustGateClientOptions } from 'trustgate-client';

// Define options with TypeScript types
const options: TrustGateClientOptions = {
  appendTo: 'headers',
  collectEnvironment: true
};

// Create a new client with typed options
const botDetection = new TrustGateClient(options);

// Collect bot detection data
const data = botDetection.collectData();

// Create a simple HTTP client with bot detection
const httpClient = botDetection.createHttpClient();

// Use the HTTP client
httpClient.get('https://api.example.com/data')
  .then(response => console.log(response.data))
  .catch(error => console.error(error));

Advanced TypeScript Usage

import { 
  TrustGateClient, 
  TrustGateClientOptions, 
  HttpClient, 
  HttpClientResponse 
} from 'trustgate-client';

// Create a client with typed options
const botDetection = new TrustGateClient({
  appendTo: 'body',
  collectVisualFingerprint: true,
  detectAutomation: true
});

// Create an HTTP client with custom headers
const httpClient: HttpClient = botDetection.createHttpClient({
  headers: {
    'Custom-Header': 'Value'
  }
});

// Use with async/await
async function fetchData(): Promise<any> {
  try {
    const response: HttpClientResponse = await httpClient.get('https://api.example.com/data');
    return response.data;
  } catch (error) {
    console.error('Error:', error);
    throw error;
  }
}

TypeScript Configuration

The library includes a tsconfig.json file for TypeScript configuration. If you're using this library in your TypeScript project, you can build the types with:

npm run build:types

You can also check the types without emitting files:

npm run check-types

For a complete TypeScript example, see examples/typescript-example.ts.

Browser Compatibility

This library is designed for modern browsers and may not work in older browsers that don't support the required APIs.

License

MIT