IoGate

Official client library for IoGate - Privacy-first PII detection and filtering API

IoGate helps you automatically detect and mask Personally Identifiable Information (PII) in your text data, ensuring privacy compliance and data protection.

🚧 Status: Coming Soon

The IoGate API is currently under construction. This package reserves the iogate name on npm and will be fully functional soon!

Visit iogate.net for updates.

Overview

iogate is the official Node.js client for IoGate. It provides a simple API to filter PII from text before sending to external services (like LLMs), and reconstruct responses locally without additional server calls.

Features

• Simple API: Filter and reconstruct in two lines of code
• Time-Based HMAC Auth: Secure authentication without exposing secrets
• Local Reconstruction: No server round-trip for decoding
• Lazy Initialization: Fast startup, validates on first use
• TypeScript: Full type definitions included
• Retry Logic: Automatic retry for transient failures
• Node.js Only: Secure, no browser support (secrets must stay server-side)

Installation

npm install iogate

Quick Start

1. Set Environment Variables

export IOGATE_CLIENT_ID="your-client-id"
export IOGATE_SECRET_TOKEN="your-secret-token"

2. Use the Library

import iogate from 'iogate';

async function example() {
  // Filter PII before sending to external service
  const { data, mapping } = await iogate.filter(
    'Contact John at [email protected] or call 555-123-4567'
  );
  
  console.log(data);
  // "Contact user1234 at [email protected] or call 212-555-9876"
  
  // Send filtered data to external service (e.g., OpenAI)
  const response = await fetch('https://api.openai.com/v1/chat/completions', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      model: 'gpt-4',
      messages: [{ role: 'user', content: data }]
    })
  });
  
  const llmResponse = await response.json();
  
  // Reconstruct original PII locally (no server call)
  const reconstructed = iogate.reconstruct(
    llmResponse.choices[0].message.content,
    mapping
  );
  
  console.log(reconstructed);
  // Original PII restored in LLM response
}

API

iogate.filter(text: string): Promise<FilterResult>

Sends text to IoGate SaaS for PII filtering.

Parameters:

• text - Text to filter (max 10MB)

Returns:

{
  data: string;                      // Filtered text with tokens
  mapping: Record<string, string>;   // Token → Original PII
}

Throws:

• IoGateAuthError - Authentication failed
• IoGateRateLimitError - Rate limit exceeded
• IoGateRequestError - Invalid request
• IoGateServerError - Server error
• IoGateNetworkError - Network/timeout error

Example:

const { data, mapping } = await iogate.filter('Email: [email protected]');

iogate.reconstruct(text: string, mapping: Record<string, string>): string

Reconstructs text by replacing tokens with original PII. Runs locally, no server call.

Parameters:

• text - Text containing tokens
• mapping - Mapping returned from filter()

Returns: Text with original PII restored

Example:

const original = iogate.reconstruct(
  'Email: [email protected]',
  { '[email protected]': '[email protected]' }
);
// Returns: "Email: [email protected]"

iogate.initialize(): Promise<void>

Explicitly validates credentials by calling health endpoint. Optional - credentials are validated automatically on first filter() call.

Use Case: Validate credentials during application startup

Example:

try {
  await iogate.initialize();
  console.log('IoGate credentials valid');
} catch (error) {
  console.error('IoGate authentication failed:', error);
  process.exit(1);
}

Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | IOGATE_CLIENT_ID | Yes | - | Client UUID from IoGate dashboard | | IOGATE_SECRET_TOKEN | Yes | - | Secret token (64-char hex) | | IOGATE_BASE_URL | No | https://iogate.net | IoGate API base URL |

Programmatic Configuration

import { IoGateClient } from 'iogate';

const client = new IoGateClient({
  clientId: 'your-client-id',
  secretToken: 'your-secret-token',
  baseUrl: 'https://iogate.net',
  timeout: 30000,      // Request timeout (ms)
  retries: 3           // Retry attempts for transient failures
});

const { data, mapping } = await client.filter('...');

Error Handling

import { IoGateAuthError, IoGateRateLimitError } from 'iogate';

try {
  const { data, mapping } = await iogate.filter(text);
} catch (error) {
  if (error instanceof IoGateAuthError) {
    // Invalid credentials or HMAC validation failed
    console.error('Authentication failed:', error.message);
  } else if (error instanceof IoGateRateLimitError) {
    // Rate limit exceeded
    const retryAfter = error.retryAfter;  // Seconds until reset
    console.error(`Rate limited. Retry after ${retryAfter}s`);
  } else {
    // Other errors
    console.error('Error:', error.message);
  }
}

Error Classes

• IoGateAuthError: Authentication failures (401)
• IoGateRateLimitError: Rate limit exceeded (429)
• IoGateRequestError: Invalid request (400)
• IoGateServerError: Server errors (500+)
• IoGateNetworkError: Network/timeout errors

TypeScript

Full TypeScript support with comprehensive type definitions:

import iogate, { FilterResult, ReconstructMapping } from 'iogate';

const result: FilterResult = await iogate.filter('...');
const mapping: ReconstructMapping = result.mapping;

Advanced Usage

Custom Client

import { IoGateClient } from 'iogate';

const client = new IoGateClient({
  clientId: process.env.IOGATE_CLIENT_ID!,
  secretToken: process.env.IOGATE_SECRET_TOKEN!,
  baseUrl: process.env.IOGATE_BASE_URL,
  timeout: 30000,
  retries: 3
});

// Use client methods
await client.filter('...');

Retry Configuration

const client = new IoGateClient({
  // ... other config
  retries: 5,                    // Max retry attempts
  retryDelay: 1000,              // Initial delay (ms)
  retryMaxDelay: 10000,          // Max delay (ms)
  retryBackoff: 2                // Exponential backoff multiplier
});

Batch Processing

const texts = [
  'Contact [email protected]',
  'Call 555-123-4567',
  'SSN: 123-45-6789'
];

const results = await Promise.all(
  texts.map(text => iogate.filter(text))
);

// Process results...

Performance

• Filter: ~50-200ms depending on text length and PII complexity
• Reconstruct: <1ms (local operation)
• Authentication: Computed per request, <1ms
• Network: Depends on latency to IoGate SaaS

Security

Why No Browser Support?

Secret tokens must never be exposed to browsers:

• Client-side JavaScript is visible to users
• Tokens in browser can be extracted and abused
• No secure storage mechanism in browsers

Solution: Use iogate in backend services only.

Token Storage

DO:

• Store in environment variables
• Use secret management systems (AWS Secrets Manager, etc.)
• Rotate periodically
• Never commit to version control

DON'T:

• Hardcode in source
• Store in plain text files
• Share via insecure channels
• Log or expose in error messages

Troubleshooting

Authentication Errors

Error: IoGateAuthError: HMAC validation failed

Causes:

• Invalid IOGATE_SECRET_TOKEN
• Incorrect IOGATE_CLIENT_ID
• Client revoked on server
• Server time drift (>6 hours)

Solution:

• Verify credentials
• Regenerate client if needed
• Check server time synchronization

Rate Limit Errors

Error: IoGateRateLimitError: Rate limit of 1000 requests per hour exceeded

Solution:

• Wait for rate limit reset (check error.retryAfter)
• Request limit increase from administrator
• Implement request queuing/throttling

Network Errors

Error: IoGateNetworkError: Request timeout after 30000ms

Causes:

• Network connectivity issues
• Server overloaded
• Timeout too short for large requests

Solution:

• Check network connectivity
• Increase timeout configuration
• Retry with exponential backoff

Examples

See examples/ directory for complete examples:

• basic.ts: Simple filter and reconstruct
• openai-integration.ts: Integration with OpenAI
• batch-processing.ts: Processing multiple texts
• error-handling.ts: Comprehensive error handling
• custom-config.ts: Advanced configuration

Support & Resources

• Website: https://iogate.net
• Documentation: Coming soon
• GitHub: github.com/iogate/iogate
• Issues: GitHub Issues

License

MIT - see LICENSE file for details

Note: This package is currently in pre-release. The API is under construction and will be available soon. Follow iogate.net for updates!