Skip to content

themacn/trial-abuse-guard

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

3 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Trial Abuse Guard

A comprehensive npm package for preventing SaaS trial abuse through intelligent detection of suspicious sign-up patterns, including email similarity detection, temporary email blocking, IP analysis, and VPN detection.

πŸš€ Features

  • Email Similarity Detection: Identifies users creating multiple accounts with similar email addresses
  • Temporary Email Blocking: Detects and blocks disposable/temporary email services
  • IP Risk Analysis: Analyzes IP addresses for suspicious activity and hosting providers
  • VPN/Proxy Detection: Identifies connections from VPN servers, proxies, and Tor networks
  • Risk Scoring: Provides comprehensive risk scores with actionable recommendations
  • Database Integration: Built-in adapters for MongoDB, PostgreSQL, and Redis
  • Easy Integration: Simple API that works with any Node.js application
  • TypeScript Support: Fully typed for better development experience

πŸ“¦ Installation

npm install trial-abuse-guard

πŸ”§ Basic Usage

const { TrialAbuseGuard } = require('trial-abuse-guard');

const guard = new TrialAbuseGuard();

// Check a user for trial abuse - exactly as requested!
const result = await guard.checkUser(
  '[email protected]',
  '192.168.1.100'
);

console.log(result.recommendation); // 'allow', 'flag', or 'block'
console.log(result.overall); // Risk score 0-100
console.log(result.details); // Detailed explanation

πŸ—‚οΈ Persistent Temp Email Domain Management

The package automatically maintains and updates a persistent list of temporary email domains:

// Automatic updates from multiple external sources
const guard = new TrialAbuseGuard({
  tempEmailAutoUpdate: true,        // Auto-update enabled (default)
  tempEmailUpdateInterval: 24,      // Update every 24 hours
  tempEmailStoragePath: './domains.json' // Custom storage location
});

// Add your own domains to the blacklist
await guard.addTempEmailDomains(['suspicious.com', 'fake-trials.org']);

// Remove domains if needed
await guard.removeTempEmailDomains(['legit-domain.com']);

// Get statistics
const stats = guard.getTempEmailStats();
console.log(`Tracking ${stats.totalDomains} temp email domains`);

// Search domains
const results = guard.searchTempEmailDomains('temp');

// Export/Import domain lists
await guard.exportTempEmailDomains('./backup.json');
await guard.importTempEmailDomains('./custom-domains.txt');

// Force update from external sources
await guard.updateTempEmailDomains();

πŸ”Œ Easy Integration with NextAuth/Auth.js and Clerk

The package provides seamless integration with popular authentication libraries:

NextAuth/Auth.js Integration

import NextAuth from 'next-auth';
import { NextAuthTrialAbuseAdapter } from 'trial-abuse-guard/nextauth';

const trialAbuseAdapter = new NextAuthTrialAbuseAdapter({
  blockHighRisk: true,
  blockThreshold: 80,
  onUserBlocked: async (email, riskData) => {
    console.log(`Blocked user: ${email} (Risk: ${riskData.overall})`);
  }
});

export const { handlers, auth } = NextAuth(
  trialAbuseAdapter.getNextAuthConfig({
    providers: [/* your providers */],
    // Your existing config is preserved and enhanced
  })
);

Features:

  • 🚫 Automatically blocks high-risk sign-ups
  • ⚠️ Flags suspicious users for review
  • πŸ“Š Adds risk data to session and JWT
  • πŸ”§ Preserves all existing NextAuth configuration
  • 🎯 Custom callbacks for handling blocked/flagged users

Clerk Integration

// Webhook handler: app/api/webhooks/clerk/route.ts
import { ClerkTrialAbuseAdapter } from 'trial-abuse-guard/clerk';

const clerkAdapter = new ClerkTrialAbuseAdapter({
  blockHighRisk: true,
  clerkSecretKey: process.env.CLERK_SECRET_KEY,
  onUserBlocked: async (email, riskData) => {
    // User is automatically deleted from Clerk
    console.log(`Blocked and deleted: ${email}`);
  }
});

export async function POST(request) {
  const webhookHandler = clerkAdapter.createWebhookHandler();
  return Response.json(await webhookHandler(request));
}

Features:

  • πŸ—‘οΈ Automatically deletes high-risk users
  • 🏷️ Adds risk metadata to user profiles
  • πŸ›‘οΈ Middleware for route protection
  • πŸ“Š Admin dashboard integration
  • ⚑ Real-time risk assessment

Pre-signup Risk Checking

// Check risk before allowing signup
const { allowed, risk, action } = await clerkAdapter.preSignUpCheck(
  email, 
  ipAddress
);

if (!allowed) {
  return res.status(403).json({ error: 'Sign-up not available' });
}

βš™οΈ Configuration

const { TrialAbuseGuard, MongoStorageAdapter } = require('trial-abuse-guard');

// Configure with MongoDB storage
const mongoAdapter = new MongoStorageAdapter({
  connectionString: 'mongodb://localhost:27017',
  databaseName: 'myapp'
});

await mongoAdapter.connect();

const guard = new TrialAbuseGuard({
  // Detection settings
  emailSimilarityCheck: true,
  emailSimilarityThreshold: 0.8,
  tempEmailCheck: true,
  ipCheck: true,
  vpnCheck: true,
  
  // Custom disposable domains
  customDisposableDomains: ['mydisposable.com'],
  
  // API keys for enhanced detection
  apiKeys: {
    ipQualityScore: 'your-api-key',
    vpnapi: 'your-api-key',
    proxyCheck: 'your-api-key'
  },
  
  // Storage adapter
  storageAdapter: mongoAdapter
});

πŸ”Œ Framework Integration

Express.js

const express = require('express');
const { TrialAbuseGuard } = require('trial-abuse-guard');

const app = express();
const guard = new TrialAbuseGuard();

app.post('/register', async (req, res) => {
  const { email } = req.body;
  const ipAddress = req.ip;
  
  const risk = await guard.checkUser(email, ipAddress);
  
  if (risk.recommendation === 'block') {
    return res.status(403).json({ 
      error: 'Registration blocked due to security concerns' 
    });
  }
  
  // Proceed with registration...
});

Next.js API Route

// pages/api/register.ts
import { TrialAbuseGuard } from 'trial-abuse-guard';

const guard = new TrialAbuseGuard();

export default async function handler(req, res) {
  const { email } = req.body;
  const ipAddress = req.headers['x-forwarded-for'] || req.connection.remoteAddress;
  
  const risk = await guard.checkUser(email, ipAddress);
  
  if (risk.recommendation === 'block') {
    return res.status(403).json({ error: 'Registration not available' });
  }
  
  // Continue with registration...
}

πŸ’Ύ Storage Adapters

MongoDB

const { MongoStorageAdapter } = require('trial-abuse-guard');

const mongoAdapter = new MongoStorageAdapter({
  connectionString: 'mongodb://localhost:27017',
  databaseName: 'myapp',
  collectionName: 'trial_users' // optional
});

PostgreSQL

const { PostgreSQLStorageAdapter } = require('trial-abuse-guard');

const pgAdapter = new PostgreSQLStorageAdapter({
  connectionString: 'postgresql://user:pass@localhost/mydb',
  tableName: 'trial_users' // optional
});

Redis

const { RedisStorageAdapter } = require('trial-abuse-guard');

const redisAdapter = new RedisStorageAdapter({
  host: 'localhost',
  port: 6379,
  password: 'your-password', // optional
  keyPrefix: 'trial_abuse:' // optional
});

🎯 Risk Assessment

The package returns a comprehensive risk assessment:

{
  overall: 75,                    // Overall risk score (0-100)
  recommendation: 'flag',         // 'allow', 'flag', or 'block'
  factors: {
    emailSimilarity: {
      score: 85,
      detected: true,
      confidence: 0.9,
      details: "Similar to existing emails: [email protected]"
    },
    tempEmail: {
      score: 0,
      detected: false,
      confidence: 0.05,
      details: "Email appears legitimate"
    },
    ipRisk: {
      score: 60,
      detected: true,
      confidence: 0.8,
      details: "IP Risk Score: 60, Country: US"
    },
    vpnDetection: {
      score: 80,
      detected: true,
      confidence: 0.9,
      details: "VPN/Proxy detected: VPN=true, Proxy=false, Tor=false"
    }
  },
  details: [
    "Similar to existing emails: [email protected]",
    "VPN/Proxy detected: VPN=true, Proxy=false, Tor=false"
  ]
}

πŸ”‘ API Keys (Optional but Recommended)

For enhanced detection accuracy, obtain API keys from:

The package works without API keys but with reduced detection capabilities.

πŸ“Š Risk Levels

Score Level Recommendation Action
0-29 Low Allow Proceed normally
30-59 Medium Flag Manual review recommended
60-79 High Flag Enhanced monitoring
80-100 Critical Block Deny access

πŸ› οΈ Advanced Usage

Custom Storage Adapter

class CustomStorageAdapter {
  async getExistingEmails() {
    // Return array of existing emails
    return ['[email protected]', '[email protected]'];
  }
  
  async getExistingIPs(email) {
    // Return array of IPs for this email
    return ['192.168.1.1', '203.0.113.1'];
  }
  
  async storeUserData(data) {
    // Store user data for future comparisons
    console.log('Storing:', data);
  }
}

const guard = new TrialAbuseGuard({
  storageAdapter: new CustomStorageAdapter()
});

Individual Detectors

const { 
  EmailSimilarityDetector, 
  TempEmailDetector, 
  IPAnalyzer, 
  VPNDetector 
} = require('trial-abuse-guard');

// Use individual detectors for specific needs
const emailDetector = new EmailSimilarityDetector(config);
const result = await emailDetector.checkSimilarity('[email protected]');

πŸ§ͺ Testing

npm test
npm run test:watch
npm run test:coverage

🀝 Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

πŸ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

πŸ”’ Security

This package is designed to enhance security but should be part of a comprehensive security strategy. Always:

  • Keep your API keys secure
  • Regularly update the package
  • Monitor and adjust risk thresholds based on your needs
  • Implement proper logging and monitoring

πŸ“ˆ Performance

  • Lightweight with minimal dependencies
  • Async/await support for non-blocking operations
  • Caching strategies for improved performance
  • Configurable timeouts for external API calls

πŸ†˜ Support

πŸ—£οΈ Also by the Creators: Jotchats

Jotchats Logo

Transform your web forms into engaging, AI-powered conversations with Jotchats. Instead of static fields, guide users through natural, full-screen dialogues that feel like chatting with a helpful assistant.

Why Jotchats?

  • πŸš€ Higher Conversion Rates - See significant improvements in response rates vs. traditional forms
  • 🎯 Better Data Collection - Collect more accurate, detailed information through conversational flows
  • 🎨 Brand Integration - Customize the experience to match your brand perfectly
  • πŸ“Š Smart Analytics - Track engagement and optimize your forms
  • πŸ”— Easy Integration - Embed seamlessly into websites, apps, or existing workflows

Perfect for lead capture, onboarding, surveys, feedback, and more. Replace clunky forms with something that actually drives results!

Learn more about Jotchats | Jotchats vs Typeform Comparison


Made with ❀️ for the developer community

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors