IntegrityGuard Documentation

Complete guide to integrating privacy-first API protection

Installation

IntegrityGuard is distributed as a commercial middleware package with three licensing tiers. After purchasing a license, you'll receive a downloadable ZIP package containing the middleware and documentation specific to your tier.

# Download your tier-specific package from customer portal
# https://integrityguard-license-api.onrender.com/portal

# Extract the downloaded package
unzip integrityguard-professional-v1.0.0.zip
cd integrityguard

# Install dependencies (Professional/Enterprise tiers)
npm install

# For Developer tier - direct integration
const IntegrityGuard = require('./integrityguard.js');

Package Contents by Tier

  • Developer ($499/year): integrityguard.js + basic documentation
  • Professional ($2,999 one-time): Source code + build scripts + integration examples
  • Enterprise ($50,000+ annually): Full source + config templates + admin tools

Quick Start

Get IntegrityGuard running in under 5 minutes. Choose your integration based on your license tier:

Developer Tier - Basic Integration

const express = require('express');
const IntegrityGuard = require('./integrityguard.js');

const app = express();

// Initialize with your license key (received via email)
const guard = new IntegrityGuard({
    licenseKey: 'IG-DEV-YOURAPP-20241201-a1b2c3d4',
    difficulty: 65536,  // Standard difficulty
    challengeExpiry: 300000 // 5 minutes
});

// Protect expensive endpoints
app.use('/api/expensive-operation', guard.middleware());

app.get('/api/expensive-operation', (req, res) => {
    res.json({ 
        message: 'Protected endpoint accessed!',
        proof: req.integrityProof // Proof details available
    });
});

app.listen(3000);

Professional/Enterprise - Advanced Integration

const express = require('express');
const { IntegrityGuard } = require('./src/integrityguard.source.js');

const app = express();

// Advanced configuration with dynamic features
const guard = new IntegrityGuard({
    licenseKey: 'IG-PRO-YOURAPP-20241201-x9y8z7w6',
    
    // Dynamic difficulty adjustment based on solve times
    dynamicDifficulty: true,
    baseThreshold: 29273, // Threshold-based (more precise than leading zeros)
    adjustmentFactor: 0.1,
    
    // Built-in rate limiting
    rateLimiting: {
        windowMs: 60000, // 1 minute
        maxAttempts: 10
    },
    
    // Metrics collection
    metrics: true,
    
    // Event handlers
    onChallengeSolved: (challenge, proof, solvetime) => {
        console.log(`Challenge solved in ${solvetime}ms`);
    },
    onAbuseDetected: (ip, pattern) => {
        console.log(`Potential abuse from ${ip}: ${pattern}`);
    }
});

// Protect endpoints with different rules
app.use('/api/ai/*', guard.middleware({
    threshold: 50000, // Higher difficulty for AI endpoints
    bypassPremium: true // Premium users skip proof-of-work
}));

app.listen(3000);

Configuration Options

Comprehensive configuration options vary by license tier. Professional/Enterprise tiers include advanced features not available in Developer tier.

Core Options (All Tiers)

Option Type Default Description
licenseKey String Required Your license key (format: IG-TIER-APP-DATE-HASH)
difficulty Number 65536 Threshold difficulty (lower = harder)
challengeExpiry Number 300000 Challenge expiry in milliseconds
algorithm String 'SHA-256' Hash algorithm for proof-of-work

Professional/Enterprise Advanced Options

Option Type Default Description
dynamicDifficulty Boolean false Auto-adjust difficulty based on solve times
baseThreshold Number 29273 Base threshold for dynamic adjustment
rateLimiting Object null Built-in rate limiting configuration
metrics Boolean false Enable metrics collection and events
onChallengeSolved Function null Event handler for successful challenges
onAbuseDetected Function null Event handler for suspicious activity

Express.js Integration

Detailed guide for integrating IntegrityGuard with Express.js applications.

Basic Setup

const express = require('express');
const { IntegrityGuard } = require('@integrity-guard/core');

const app = express();

// Apply authentication middleware first
app.use('/api/*', authenticateToken);

// Initialize IntegrityGuard after authentication
const guard = new IntegrityGuard({
    licenseKey: process.env.INTEGRITY_GUARD_LICENSE,
    tiers: {
        anonymous: { 
            difficulty: 500000, 
            description: 'Anonymous users',
            estimatedTime: '30-120 seconds' 
        },
        authenticated: { 
            difficulty: 200000, 
            description: 'Free registered users',
            estimatedTime: '15-60 seconds' 
        },
        premium: { 
            difficulty: 25000, 
            description: 'Premium subscribers',
            estimatedTime: '1-3 seconds' 
        }
    },
    getUserTier: (req) => {
        // Your user tier logic
        if (req.user?.subscription === 'premium') return 'premium';
        if (req.user) return 'authenticated';
        return 'anonymous';
    }
});

// Protect specific routes
app.use('/api/expensive-ai-call', guard.middleware());
app.use('/api/resource-intensive', guard.middleware());

Advanced Configuration

// Dynamic difficulty based on server load
const guard = new IntegrityGuard({
    licenseKey: process.env.INTEGRITY_GUARD_LICENSE,
    tiers: {
        anonymous: { 
            difficulty: () => {
                const load = getServerLoad();
                return Math.max(250000, load * 10000);
            }
        },
        premium: { difficulty: 25000 }
    },
    getUserTier: (req) => {
        // Custom tier detection
        const tier = req.user?.subscription || 'anonymous';
        
        // Support for test tokens
        if (req.headers.authorization) {
            const token = req.headers.authorization.split(' ')[1];
            if (isTestToken(token)) {
                return getTestTier(token);
            }
        }
        
        return tier === 'premium' ? 'premium' : 'anonymous';
    },
    onChallengeSolved: (req, proof, tier) => {
        console.log(`Challenge solved by ${tier} user in ${proof.computeTime}ms`);
    }
});

User Tiers

How to configure different proof-of-work difficulties for different user types.

Common Tier Configurations

Freemium Model

tiers: {
    anonymous: { 
        difficulty: 500000,
        estimatedTime: '30-120 seconds',
        description: 'Encourages signup'
    },
    free: { 
        difficulty: 200000,
        estimatedTime: '15-60 seconds',
        description: 'Basic registered users' 
    },
    premium: { 
        difficulty: 25000,
        estimatedTime: '1-3 seconds',
        description: 'Premium subscribers'
    }
}

Enterprise Model

tiers: {
    public: { 
        difficulty: 1000000,
        estimatedTime: '2-5 minutes',
        description: 'Public API access'
    },
    partner: { 
        difficulty: 100000,
        estimatedTime: '5-15 seconds',
        description: 'Partner API access'
    },
    enterprise: { 
        difficulty: 10000,
        estimatedTime: '1 second',
        description: 'Enterprise customers'
    }
}

API Reference

Constructor

new IntegrityGuard(options)

Creates a new IntegrityGuard instance with the specified configuration.

Parameters
  • options (Object) - Configuration options
Returns

IntegrityGuard instance

Middleware Methods

guard.middleware()

Returns Express middleware function that enforces proof-of-work challenges.

Returns

Express middleware function

// Basic usage
app.use('/api/protected', guard.middleware());

// With custom options
app.use('/api/special', guard.middleware({
    customDifficulty: 100000,
    skipFor: (req) => req.ip === '127.0.0.1'
}));

Instance Methods

guard.generateChallenge(tier)

Generates a new proof-of-work challenge for the specified tier.

Parameters
  • tier (String) - User tier name
Returns

Promise resolving to challenge object

guard.verifyProof(challenge, proof)

Verifies a proof-of-work solution against a challenge.

Parameters
  • challenge (Object) - Original challenge
  • proof (Object) - Proof solution
Returns

Boolean indicating if proof is valid

Troubleshooting

Common Issues

License Key Issues

Error: Invalid license key format

// Solution: Ensure your license key matches the format
licenseKey: 'IG-PRO-YOURAPP-YYYYMMDD-checksum'

getUserTier Function Errors

// Problem: getUserTier returns undefined
getUserTier: (req) => {
    return req.user?.tier; // May return undefined
}

// Solution: Always return a valid tier
getUserTier: (req) => {
    return req.user?.tier || 'anonymous';
}

Client-Side Integration

Make sure to include the client-side JavaScript for handling proof-of-work challenges:

<script src="https://cdn.integrity-guard.com/client/v1/integrity-guard-client.js"></script>

🎯 Getting Your License

IntegrityGuard offers three commercial tiers designed for different business needs:

Developer - $499/year

Perfect for: Startups & indie developers

  • Basic integrityguard.js middleware
  • 1 production domain
  • 12 months of updates
  • Email support
  • Commercial use rights

Enterprise - $50,000+ annually

Perfect for: Large organizations, AI providers

  • Everything in Professional
  • Unlimited domains
  • SLA & dedicated support
  • Real-time metrics dashboard
  • Architecture consulting
  • Dedicated account manager

📦 What Happens After Purchase

  1. Instant Access: Login to customer portal immediately
  2. Download Package: Get your tier-specific ZIP file
  3. License Key: Receive key via email (format: IG-TIER-APP-DATE-HASH)
  4. Integration: Follow tier-specific setup guide
  5. Support: Access to email support and documentation

Support & Resources

Complete support system with multiple channels for different needs:

📧 Technical Support

Integration help, troubleshooting, bug reports

Get Technical Help

💬 Sales & Licensing

Pricing questions, license upgrades, custom needs

Contact Sales

🏪 Customer Portal

Access downloads, manage licenses, view usage

Customer Login