VeilProof SDK

Behavioral telemetry SDK for invisible bot detection and fraud prevention.

Current package / CDN target: 1.1.10. Binary allow/block only (no challenge). Production API: https://api.veilproof.tech — strict signing, stealth + stacked coherence + computer-use kinematics, CF Worker ASN.

Installation

Script tag — zero JS (any HTML site: WordPress, Django templates, Rails views, ...)

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/veilproof.min.js"
        data-site-key="vp_site_..."
        async defer></script>

That's it — the SDK auto-initializes from the data-site-key attribute. Add data-debug="true" for console logging, or data-endpoint="..." to override the API host.

For a classic HTML <form> that posts to your server, add data-veilproof and the SDK injects a hidden veilproof-token field before the real submit:

<form data-veilproof action="/signup" method="post">
  <input name="email" type="email" required>
  <button type="submit">Sign up</button>
</form>

Your server then redeems that token with your secret key at POST /api/siteverify — see Server-side verification below. Never put your secret key (vp_secret_...) in browser code — the SDK will refuse to initialize with one.

Via npm (React/Vue/Next.js)

npm install veilproof

import VeilProof from 'veilproof';

// Read the site key from your bundler's env convention (NEXT_PUBLIC_*,
// VITE_*, REACT_APP_*, webpack DefinePlugin, ...) rather than a string
// literal — not a secret, since it ships in the browser bundle either way,
// but a literal scattered across source files is still sloppy config hygiene.
VeilProof.init({
  apiKey: process.env.NEXT_PUBLIC_VEILPROOF_SITE_KEY // your site key — never your secret key
});

Quick Start

// Initialize the SDK with your site key
VeilProof.init({
  apiKey: process.env.NEXT_PUBLIC_VEILPROOF_SITE_KEY,
  debug: true // Enable for development
});

// Get a token and send it to your server for verification
VeilProof.getToken((result) => {
  fetch('/my-api/submit', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ veilproofToken: result.token, /* ...your form data */ })
  });
});

Server-side verification (siteverify)

The browser's decision is not a trust boundary — a bot can ignore or fake it. Your server must redeem the token with your secret key (vp_secret_..., never exposed to the browser) at POST /api/siteverify before trusting the request:

curl -X POST https://api.veilproof.tech/api/siteverify \
  -H "X-API-Key: vp_secret_..." \
  -H "Content-Type: application/json" \
  -d '{"token": "<token from the browser>"}'

{ "success": true, "risk_score": 12, "action": "allow", "hostname": "example.com" }

Tokens are single-use and expire after 120 seconds. On failure, the response is still HTTP 200 with {"success": false, "error-codes": [...]} — check success, not the status code.

API Reference

VeilProof.init(config)

Initialize the SDK with your configuration.

Parameters:

• config.apiKey (string, required) - Your site key (vp_site_...) from the dashboard. Never pass a secret key (vp_secret_...) here — the SDK rejects it.
• config.endpoint (string, optional) - Backend API URL (default: https://api.veilproof.tech)
• config.debug (boolean, optional) - Enable debug logging (default: false)
• config.disableTelemetry (boolean, optional) - Disable telemetry sending (default: false)

VeilProof.getDecision(callback)

Get a bot detection decision based on collected behavioral data.

Parameters:

• callback (function) - Callback function receiving the decision result

Result:

{
  action: 'allow' | 'block', // binary — no 'challenge' tier is implemented anywhere in the product
  risk_score: 0-100,         // combined risk score; >=50 blocks
  behavior_score: 0-100,     // VeilProof's behavioral risk signal
  fingerprint_score: 0-100,  // VeilProof's device/environment risk signal
  confidence: 0.0-1.0,       // distance of risk_score from the 50-point decision boundary
  error: undefined // present with action: 'block' if the request itself failed
}

getDecision fails closed: if the request to /api/predict errors, times out, or the API key/domain is rejected, the callback receives { action: 'block', risk_score: 100, error: '<reason>' } rather than an uncaught exception.

VeilProof.getToken(callback?)

Get a verification token for your server to redeem at /api/siteverify. Wraps getDecision — same failure semantics. Supports both a callback and a Promise:

// Callback style
VeilProof.getToken((result) => {
  // result.token, result.decision, result.error
});

// Promise style
const result = await VeilProof.getToken();

Result:

{
  token: 'eyJhbGci...' | null, // null if acquisition failed — fail open in your integration
  decision: { action, risk_score, ... }, // same shape as getDecision's result
  error: undefined // present if the underlying request failed
}

VeilProof.getSessionId()

Get the current session ID.

Returns: (string) Session identifier

VeilProof.getSessionMeta()

Get session metadata including start time and platform info.

Returns: (object) Session metadata

VeilProof.getDebugSnapshot()

Get current SDK state for troubleshooting.

Returns: (object) Debug snapshot with version, session info, buffer state, and recent events

VeilProof.selfTest(callback)

Run self-test to verify SDK integration.

Parameters:

• callback (function) - Callback receiving test results

Result:

{
  version: '1.1.2',
  tests: [
    { name: 'SDK Initialized', status: 'pass' },
    { name: 'API Key Valid', status: 'pass' },
    { name: 'Events Collected', status: 'pass' },
    { name: 'Network Reachable', status: 'pass' }
  ],
  passed: 4,
  failed: 0,
  overall: 'pass'
}

VeilProof.destroy()

Stop all tracking and flush remaining events.

Failure behavior

• Never throws into the host page. Collector start/stop and teardown calls are wrapped internally — a bug in one collector is logged to console.warn and suppressed, not propagated.
• SSR-safe. init() no-ops with a console warning when window/document are unavailable (Next.js App Router server components, etc).
• Fails closed on /api/predict errors. See getDecision above — this is a deliberate default for a security product; revisit if a backend outage should not block real users on your integration.

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Mobile browsers (iOS Safari, Chrome Mobile)

Development

# Install dependencies
npm install

# Build all formats
npm run build

# Development mode with watch
npm run dev

# Prepare for npm publish
npm run prepublishOnly

License

MIT — see LICENSE.