JavaScript widget

The JS widget hooks any HTML form's submit event, scores it via Veritus, and lets you respond per verdict. ~5KB minified, no dependencies, no build step.

Loading

<script src="https://api.veritus.uk/v1/widget.js"></script>

Cached for 5 minutes. Once loaded, exposes window.Veritus with protect, score, and version.

Basic usage

Veritus.protect({
  form:     '#signup-form',    // CSS selector or Element
  formUuid: 'YOUR-FORM-UUID',  // from /dashboard/forms/<id>
});

With just that, the widget will:

• Inject a hidden honeypot field
• Intercept form submit
• Collect standard field names (email, phone, name, country, postcode, etc.)
• Score the signup via /v1/widget/score
• On allow: let the form submit naturally (with a hidden _veritus_request_id field)
• On review: add a _veritus_review=1 hidden field and let it submit
• On block: show an alert and prevent submission
• On Veritus error/down: let the form submit anyway (fail-open default)

All callbacks

Veritus.protect({
  form:     '#signup-form',
  formUuid: 'YOUR-FORM-UUID',

  onAllow:  (result) => {
    // Optional - form will submit anyway
    console.log('Allowed:', result.request_id);
  },

  onReview: (result) => {
    // Return false to stop submission, true (default) to submit with flag
    if (confirm('Additional verification may be required. Continue?')) {
      return true;
    }
    return false;
  },

  onBlock:  (result) => {
    // Show your own block message
    document.getElementById('error').textContent = 'We were unable to process this signup. Please contact support and reference ' + result.request_id;
  },

  onError:  (err) => {
    // Called only if failClosed:true and Veritus is down
    console.error('Veritus unavailable:', err);
  },

  failClosed: false,  // default false (fail-open: if Veritus is down, submit anyway)
});

Field name conventions

The widget reads these field names automatically. If your form uses different names, either rename them or wire it up manually with Veritus.score():

name	Also reads: fullname, full_name
email	Required-ish
phone	Also reads: mobile, tel
country	ISO-2 ideally
postcode	Also reads: zip, zip_code
address_line	Also reads: address, address1
password	Also reads: pw. Used for HIBP check — never stored.

Manual usage with Veritus.score()

If protect() doesn't fit, you can call the scorer directly:

const result = await Veritus.score({
  formUuid: 'YOUR-FORM-UUID',
  signup: {
    email:    document.getElementById('my-email').value,
    country:  'GB',
    // ip is stamped server-side
  },
});
// result = { verdict: 'allow' | 'review' | 'block', request_id: '...' }

Security considerations

• The form UUID is public — safe to put in client-side code
• Configure origin_url on your form to prevent UUID theft + abuse from other sites
• Widget verdicts are sanitised (no score/reasons in response) so attackers can't probe the model
• Don't rely on widget-only blocking — a malicious user could modify the page to skip it. For high-stakes flows, re-score server-side with an API key.