{"_id":"@apachewarrior23/form-guardian","name":"@apachewarrior23/form-guardian","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@apachewarrior23/form-guardian","version":"1.0.0","description":"Advanced form validation and protection utility for web applications","type":"module","main":"dist/index.js","module":"dist/index.esm.js","types":"dist/index.d.ts","scripts":{"build":"rollup -c","dev":"rollup -c -w","test":"jest","prepublishOnly":"npm run build"},"keywords":["form","validation","security","web","frontend","protection","spam","filter"],"author":{"name":"Jordan Boyce"},"license":"MIT","devDependencies":{"@rollup/plugin-commonjs":"^25.0.0","@rollup/plugin-node-resolve":"^15.0.0","@rollup/plugin-typescript":"^11.0.0","@types/jest":"^29.0.0","jest":"^29.0.0","jest-environment-jsdom":"^30.2.0","rollup":"^3.0.0","ts-jest":"^29.4.5","tslib":"^2.8.1","typescript":"^5.0.0"},"repository":{"type":"git","url":"git+https://github.com/JordanBoyce/form-guardian.git"},"bugs":{"url":"https://github.com/JordanBoyce/form-guardian/issues"},"homepage":"https://github.com/JordanBoyce/form-guardian#readme","_id":"@apachewarrior23/form-guardian@1.0.0","gitHead":"2b61aa09bfead3c34911c0ebe3a902db3e823b7f","_nodeVersion":"22.16.0","_npmVersion":"11.5.2","dist":{"integrity":"sha512-bNLU+BzDC9O09dpWzJSOMmWxBQtwWJ3uJGWAivJB0Hyz9oQ6w1NVNLCE+zw2j8Tc3WxPHt+1qZvGQXuWWcpBwQ==","shasum":"aedd76a77301eeef1aaddcaf32ddd33d4298a242","tarball":"https://registry.npmjs.org/@apachewarrior23/form-guardian/-/form-guardian-1.0.0.tgz","fileCount":15,"unpackedSize":299133,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC2g40z/1nBUGVywdDXQylDhEZMyyx+2MD3Zgk+rYXaFgIgbUSrCDMox2P9shnq2x0jktq6HbdiKti98vCAlN9pG4w="}]},"_npmUser":{"name":"apachewarrior23","email":"jordan.boyce@cyberlion.dev"},"directories":{},"maintainers":[{"name":"apachewarrior23","email":"jordan.boyce@cyberlion.dev"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/form-guardian_1.0.0_1762025128343_0.8939688389986908"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-01T19:25:28.235Z","1.0.0":"2025-11-01T19:25:28.505Z","modified":"2025-11-01T19:25:28.754Z"},"maintainers":[{"name":"apachewarrior23","email":"jordan.boyce@cyberlion.dev"}],"description":"Advanced form validation and protection utility for web applications","homepage":"https://github.com/JordanBoyce/form-guardian#readme","keywords":["form","validation","security","web","frontend","protection","spam","filter"],"repository":{"type":"git","url":"git+https://github.com/JordanBoyce/form-guardian.git"},"author":{"name":"Jordan Boyce"},"bugs":{"url":"https://github.com/JordanBoyce/form-guardian/issues"},"license":"MIT","readme":"# Form Guardian 🛡️\r\n\r\nAdvanced form validation and protection utility that intelligently detects and blocks automated bot submissions while maintaining a seamless experience for legitimate users.\r\n\r\n## Features\r\n\r\n- **Smart Honeypot Fields** - Context-aware invisible fields that attract bots\r\n- **Behavioral Analysis** - Tracks mouse movements, typing patterns, and interaction sequences\r\n- **Timing Analysis** - Detects suspiciously fast or robotic form completion\r\n- **Browser Fingerprinting** - Identifies headless browsers and automation tools\r\n- **Flexible Integration** - Works with any form, framework, or CMS\r\n- **Zero Friction** - Invisible to legitimate users\r\n- **Configurable Scoring** - Adjustable sensitivity levels\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install form-guardian\r\n```\r\n\r\n## Quick Start\r\n\r\n### Automatic Protection (Easiest)\r\n\r\nJust add a data attribute to your forms:\r\n\r\n```html\r\n<script src=\"form-guardian.js\" data-auto-init=\"true\"></script>\r\n\r\n<form data-bot-protection=\"true\" data-min-time=\"5000\">\r\n  <input type=\"text\" name=\"name\" required>\r\n  <input type=\"email\" name=\"email\" required>\r\n  <textarea name=\"message\"></textarea>\r\n  <button type=\"submit\">Send</button>\r\n</form>\r\n```\r\n\r\n### Manual Protection\r\n\r\n```javascript\r\nimport FormGuardian from 'form-guardian';\r\n\r\nconst guardian = new FormGuardian({\r\n  debug: true,\r\n  scoreThreshold: 70\r\n});\r\n\r\n// Protect specific forms\r\nguardian.protect('#contact-form', {\r\n  minFillTime: 8000,\r\n  onSubmit: (data) => {\r\n    if (!data.blocked) {\r\n      // Process legitimate submission\r\n      console.log('Valid submission:', data.formData);\r\n    }\r\n  },\r\n  onBlock: (reason, score) => {\r\n    console.log('Blocked submission:', reason, score);\r\n  }\r\n});\r\n```\r\n\r\n### Framework Integration\r\n\r\n#### React\r\n\r\n```jsx\r\nimport { useEffect } from 'react';\r\nimport FormGuardian from 'form-guardian';\r\n\r\nfunction ContactForm() {\r\n  useEffect(() => {\r\n    const guardian = new FormGuardian();\r\n    guardian.protect('#contact-form');\r\n    \r\n    return () => guardian.destroy();\r\n  }, []);\r\n\r\n  return (\r\n    <form id=\"contact-form\">\r\n      <input name=\"name\" type=\"text\" placeholder=\"Your Name\" />\r\n      <input name=\"email\" type=\"email\" placeholder=\"Your Email\" />\r\n      <textarea name=\"message\" placeholder=\"Your Message\"></textarea>\r\n      <button type=\"submit\">Send Message</button>\r\n    </form>\r\n  );\r\n}\r\n```\r\n\r\n#### Vue\r\n\r\n```vue\r\n<template>\r\n  <form ref=\"contactForm\">\r\n    <input name=\"name\" type=\"text\" placeholder=\"Your Name\" />\r\n    <input name=\"email\" type=\"email\" placeholder=\"Your Email\" />\r\n    <textarea name=\"message\" placeholder=\"Your Message\"></textarea>\r\n    <button type=\"submit\">Send Message</button>\r\n  </form>\r\n</template>\r\n\r\n<script>\r\nimport FormGuardian from 'form-guardian';\r\n\r\nexport default {\r\n  mounted() {\r\n    this.guardian = new FormGuardian();\r\n    this.guardian.protect(this.$refs.contactForm);\r\n  },\r\n  beforeDestroy() {\r\n    this.guardian?.destroy();\r\n  }\r\n}\r\n</script>\r\n```\r\n\r\n## Configuration Options\r\n\r\n### Guardian Options\r\n\r\n```javascript\r\nconst guardian = new FormGuardian({\r\n  autoInit: true,           // Auto-protect forms with data attributes\r\n  debug: false,             // Enable console logging\r\n  globalMinTime: 3000,      // Default minimum fill time (ms)\r\n  globalMaxTime: 300000,    // Default maximum fill time (ms)\r\n  defaultHoneypots: 2,      // Number of honeypot fields to inject\r\n  scoreThreshold: 70,       // Block threshold (0-100)\r\n  endpoint: '/api/verify'   // Optional server-side validation endpoint\r\n});\r\n```\r\n\r\n### Form-Specific Config\r\n\r\n```javascript\r\nguardian.register('my-form', {\r\n  minFillTime: 8000,        // Minimum time to fill form\r\n  maxFillTime: 600000,      // Maximum time before timing out\r\n  behaviorTracking: true,   // Track mouse/keyboard behavior\r\n  fingerprintTracking: true, // Browser fingerprinting\r\n  honeypotFields: ['backup_email', 'website'], // Custom honeypot field names\r\n  \r\n  onSubmit: (data) => {\r\n    // Handle valid submissions\r\n    console.log('Form data:', data.formData);\r\n    console.log('Analysis score:', data.score);\r\n  },\r\n  \r\n  onBlock: (reason, score) => {\r\n    // Handle blocked submissions\r\n    console.log('Blocked:', reason);\r\n    // Maybe show CAPTCHA or additional verification\r\n  }\r\n});\r\n```\r\n\r\n## Detection Methods\r\n\r\n### Honeypot Fields\r\nInvisible form fields that bots typically fill but humans cannot see:\r\n\r\n```html\r\n<!-- These are automatically injected and hidden -->\r\n<input type=\"email\" name=\"email_confirmation\" style=\"display: none;\">\r\n<input type=\"url\" name=\"website_url\" style=\"position: absolute; left: -9999px;\">\r\n```\r\n\r\n### Timing Analysis\r\n- **Too Fast**: Form completed in under 3 seconds (configurable)\r\n- **Too Slow**: Form abandoned for hours then suddenly submitted\r\n- **Robotic Patterns**: Perfectly regular typing intervals\r\n\r\n### Behavioral Analysis\r\n- **No Mouse Movement**: Bots often don't simulate mouse movement\r\n- **No Keyboard Input**: Copy-paste only behavior\r\n- **Unnatural Field Order**: Bots may fill fields programmatically\r\n- **Missing Focus Events**: Real users focus on fields before typing\r\n\r\n### Browser Fingerprinting\r\n- **Webdriver Detection**: Automation tools leave traces\r\n- **Headless Browsers**: Missing window properties\r\n- **Suspicious User Agents**: Bot-like browser signatures\r\n\r\n## Scoring System\r\n\r\nForm Guardian uses a 0-100 scoring system:\r\n\r\n- **0-30**: Likely human (allow submission)\r\n- **31-70**: Suspicious (consider additional verification)\r\n- **71-100**: Likely bot (block submission)\r\n\r\nScores are cumulative based on multiple detection methods:\r\n- Honeypot interaction: +80 points\r\n- No mouse movement: +40 points\r\n- Too fast completion: +50 points\r\n- Webdriver detected: +60 points\r\n\r\n## Server-Side Integration\r\n\r\n### Express.js Middleware\r\n\r\n```javascript\r\nconst express = require('express');\r\nconst app = express();\r\n\r\napp.post('/contact', (req, res) => {\r\n  const { _guardian_score, _guardian_reasons, ...formData } = req.body;\r\n  \r\n  if (_guardian_score > 70) {\r\n    return res.status(400).json({ \r\n      error: 'Submission blocked',\r\n      reason: _guardian_reasons \r\n    });\r\n  }\r\n  \r\n  // Process legitimate submission\r\n  processContactForm(formData);\r\n  res.json({ success: true });\r\n});\r\n```\r\n\r\n### PHP Validation\r\n\r\n```php\r\n<?php\r\nif ($_POST['_guardian_score'] > 70) {\r\n    http_response_code(400);\r\n    echo json_encode(['error' => 'Submission blocked']);\r\n    exit;\r\n}\r\n\r\n// Process form data\r\n$clean_data = array_filter($_POST, function($key) {\r\n    return !str_starts_with($key, '_guardian_');\r\n}, ARRAY_FILTER_USE_KEY);\r\n\r\nprocessForm($clean_data);\r\n?>\r\n```\r\n\r\n## Advanced Usage\r\n\r\n### Custom Analysis\r\n\r\n```javascript\r\n// Analyze a form without submitting\r\nconst analysis = await guardian.analyzeForm('my-form');\r\nconsole.log('Current score:', analysis.score);\r\nconsole.log('Detected issues:', analysis.reasons);\r\n\r\nif (analysis.score > 50) {\r\n  // Show CAPTCHA or additional verification\r\n  showCaptcha();\r\n}\r\n```\r\n\r\n### Real-time Monitoring\r\n\r\n```javascript\r\nconst guardian = new FormGuardian({\r\n  debug: true,\r\n  onSubmit: (data) => {\r\n    // Send analytics to your server\r\n    fetch('/api/form-analytics', {\r\n      method: 'POST',\r\n      headers: { 'Content-Type': 'application/json' },\r\n      body: JSON.stringify({\r\n        score: data.score,\r\n        reasons: data.reasons,\r\n        blocked: data.blocked,\r\n        formId: 'contact-form'\r\n      })\r\n    });\r\n  }\r\n});\r\n```\r\n\r\n### Progressive Enhancement\r\n\r\n```javascript\r\n// Start with basic protection, add features based on bot activity\r\nlet currentThreshold = 70;\r\n\r\nguardian.protect('#form', {\r\n  scoreThreshold: currentThreshold,\r\n  onBlock: (reason, score) => {\r\n    // If getting a lot of bots, tighten security\r\n    if (score > 90) {\r\n      currentThreshold = 60; // Lower threshold = stricter\r\n      guardian.updateConfig('form', { scoreThreshold: currentThreshold });\r\n    }\r\n  }\r\n});\r\n```\r\n\r\n## Browser Support\r\n\r\n- Chrome/Edge 60+\r\n- Firefox 55+\r\n- Safari 12+\r\n- Mobile browsers (iOS Safari, Chrome Mobile)\r\n\r\n## FAQ\r\n\r\n**Q: Will this block legitimate users?**\r\nA: Form Guardian is designed to be invisible to real users. The scoring system requires multiple suspicious signals before blocking.\r\n\r\n**Q: Can sophisticated bots bypass this?**\r\nA: While no solution is 100% foolproof, Form Guardian uses multiple detection layers that make it very difficult for automated tools to bypass.\r\n\r\n**Q: Does this work with AJAX forms?**\r\nA: Yes! Form Guardian works with any form submission method - traditional posts, AJAX, fetch, etc.\r\n\r\n**Q: What about accessibility?**\r\nA: Honeypot fields are properly hidden with ARIA attributes and don't interfere with screen readers or keyboard navigation.\r\n\r\n## License\r\n\r\nMIT License - see LICENSE file for details.\r\n\r\n## Contributing\r\n\r\nContributions welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.","readmeFilename":"README.md","_rev":"1-e3d95cfa423d8df5bfa9fe6ff5909ee5"}