ai-appshield

NPM wrapper to protect your applications from AI scrapers, bots, and reverse-engineering attempts.

• npm: ai-appshield
• GitHub: tandin2000/AI-AppShield

Install it like any npm package, use the CLI to scaffold protection into your project, and enable client + server guards with a few lines of code.

Features

| Layer | Protection | |-------|-----------| | Bot Detection | Detects Puppeteer, Selenium, Playwright, headless Chrome, and 40+ known bot user-agents | | AI Scraper Blocking | Blocks GPTBot, ClaudeBot, Bytespider, CCBot, PerplexityBot, and other AI crawlers | | DevTools Guard | Detects open developer tools via size differential, debugger timing, and console traps | | Content Protection | Disables right-click, copy, text selection, drag, and print | | Honeypot Traps | Injects hidden form fields and links that only bots fill/click | | Fingerprinting | Canvas + WebGL fingerprinting for server-side validation | | Content Obfuscation | XOR-encode sensitive text in the DOM (data-shield attributes) | | Rate Limiting | Server-side sliding-window rate limiter | | CLI Wrapper | ai-appshield init, wrap, encode, and check commands |

Install

npm install ai-appshield

Quick Start

CLI — Scaffold protection into your project

# Initialize for your framework
npx ai-appshield init --framework react
npx ai-appshield init --framework express
npx ai-appshield init --framework next
npx ai-appshield init --framework vanilla

# Inject protection script into HTML
npx ai-appshield wrap --entry index.html

# Encode sensitive text for DOM obfuscation
npx ai-appshield encode "secret API key value"

# Check if a user-agent is a bot
npx ai-appshield check "Mozilla/5.0 (compatible; GPTBot/1.0)"

Browser (Client-Side)

import { protect } from 'ai-appshield/browser';

const shield = protect({
  botDetection: true,
  devToolsGuard: true,
  contentProtection: true,
  honeypot: true,
  fingerprint: true,
  threatAction: 'warn',       // 'block' | 'warn' | 'redirect'
  onThreatDetected: (threat) => {
    console.warn('Threat:', threat.type, threat.message);
  },
});

HTML Script Tag (No Build Step)

<script src="node_modules/ai-appshield/browser/shield.min.js"></script>
<script>
  AppShield.protect({
    botDetection: true,
    devToolsGuard: true,
    contentProtection: true,
    threatAction: 'block'
  });
</script>

React Hook

import { useAppShield } from './hooks/useAppShield';

function App() {
  useAppShield();
  return <div>Protected content</div>;
}

Server (Express / Node.js)

const express = require('express');
const { createShieldMiddleware } = require('ai-appshield/server');

const app = express();

app.use(createShieldMiddleware({
  botAnalysis: true,
  blockBots: true,
  rateLimit: { maxRequests: 100, windowMs: 60000 },
  blockStatusCode: 403,
  excludePaths: ['/health'],
  onBlocked: (info) => {
    console.warn('Blocked:', info.ip, info.reason);
  },
}));

app.get('/api/data', (req, res) => {
  res.json({ secret: 'protected data' });
});

Content Obfuscation

Encode sensitive text so it's not readable in page source:

npx ai-appshield encode "Premium feature details"
# Output: <span data-shield="encoded-string"></span>

<span data-shield="KlkPGBEJDw=="></span>

Enable obfuscateContent: true in your Shield config to auto-decode at runtime.

Configuration

After running ai-appshield init, edit ai-appshield.config.js:

module.exports = {
  client: {
    botDetection: true,
    devToolsGuard: true,
    contentProtection: true,
    honeypot: true,
    fingerprint: true,
    obfuscateContent: false,
    threatAction: 'warn',
    redirectUrl: '/blocked',
    reportEndpoint: '/api/shield-report',
    debug: false,
  },
  server: {
    botAnalysis: true,
    blockBots: true,
    requireFingerprint: false,
    rateLimit: { maxRequests: 100, windowMs: 60000 },
    blockStatusCode: 403,
    excludePaths: ['/health', '/api/public'],
  },
};

API Reference

protect(config?) / new Shield(config)

| Option | Type | Default | Description | |--------|------|---------|-------------| | botDetection | boolean | true | Detect automation tools and headless browsers | | devToolsGuard | boolean | true | Detect open DevTools | | contentProtection | boolean | true | Block copy, right-click, selection | | honeypot | boolean | true | Inject hidden honeypot traps | | fingerprint | boolean | true | Collect browser fingerprint | | obfuscateContent | boolean | false | Decode data-shield elements | | threatAction | string | 'warn' | 'block', 'warn', or 'redirect' | | onThreatDetected | function | — | Callback on threat detection |

createShieldMiddleware(config)

| Option | Type | Default | Description | |--------|------|---------|-------------| | botAnalysis | boolean | true | Analyze request headers for bot signals | | blockBots | boolean | true | Block known bot user-agents | | rateLimit | object | — | { maxRequests, windowMs } | | requireFingerprint | boolean | false | Require X-Ai-Appshield-Fingerprint header | | excludePaths | string[] | — | Paths to skip protection |

Architecture

┌─────────────────────────────────────────────┐
│                  Your App                    │
├──────────────────┬──────────────────────────┤
│  Browser Shield  │     Server Shield        │
│  ├ Bot Detector  │  ├ Bot Analyzer         │
│  ├ DevTools Guard│  ├ Rate Limiter          │
│  ├ Content Guard  │  ├ Middleware           │
│  ├ Honeypot      │  └ Request Validator     │
│  └ Fingerprint   │                          │
└──────────────────┴──────────────────────────┘

Important Notes

• Defense in depth: No client-side protection is 100% bypassable. Combine browser + server guards for best results.
• AI scrapers: Server-side bot user-agent blocking is the most effective layer against AI crawlers (GPTBot, ClaudeBot, etc.).
• Legitimate bots: Use excludePaths or customize BOT_USER_AGENTS for search engines you want to allow.
• Privacy: Fingerprinting collects browser characteristics. Disclose this in your privacy policy if required.

Test

npm test

Uses Node.js built-in test runner (node:test). Tests live alongside source as *.test.ts files and cover:

• Content obfuscation encode/decode
• Bot user-agent analysis and AI crawler blocking
• Rate limiting and middleware behavior
• Honeypot validation
• Default configuration values

License

MIT

Links

• GitHub Repository
• npm Package
• Report an Issue