@findip/shield

FindIP Shield JavaScript SDK

FindIP Shield adds visitor risk intelligence to a website. The SDK reports VPN, proxy, Tor, relay, hosting, datacenter, malicious-IP, and network signals without collecting form values.

Published on npm as @findip/shield.

See Shield in action

▶ Watch with sound (0:30) · Try the interactive demo · Explore FindIP Shield

The clip uses sample data, and its captions are on screen. Three more short clips:

Add Shield with a website snippet	Choose what happens on a form	Connect through Cloudflare
Create a site, paste the snippet, see your first visit.	Protect a sign-up form and see what was recommended and what happened.	No code: authorize, choose a hostname, start in Monitor mode.

Install from npm

npm install @findip/shield

import { init, track, getSession, setConsent } from '@findip/shield';

init({
  siteKey: 'pub_xxxxxxxxx',
  privacyMode: 'balanced',
  autoTrack: true,
  autoDetectForms: true,
});

await track('signup_attempt', {
  email_domain: 'example.com',
  plan: 'free',
});

const { sessionId } = getSession();

The package provides ESM, CommonJS, and TypeScript declarations.

Identify the visitor

Tell Shield which of your users a session belongs to. The plain user ID and email never leave the page: the SDK hashes them in the browser with SHA-256, and encrypts them with your site's identity public key (RSA-OAEP, fetched from Shield once per page) so that only the Shield dashboard can show them next to each event. Shield's ingest and storage only ever see the hashes, the email domain, the plan, and the ciphertext.

init({
  siteKey: 'pub_xxxxxxxxx',
  identify: {
    userId: currentUser.id,      // sent as user_id_hash + user_id_enc
    email: currentUser.email,    // sent as email_hash + email_domain + email_enc
    plan: currentUser.plan,      // sent as plan
    salt: 'optional-secret',     // mixed into both hashes: SHA-256(salt + ':' + value)
    custom: {                    // account facts on every event (no PII)
      account_tier: currentUser.tier,
      signup_channel: 'google',
    },
  },
});

// Or later, e.g. after a login. Pass null on logout.
identify({ userId: user.id, email: user.email });

The dashboard shows the email and user ID on every identified event and session. Switch "Show visitor emails and user IDs" off in the site's settings to keep identities hash-only; the SDK then sends no ciphertext at all. Pass identityKey (or data-identity-key) with the key shown in the dashboard to skip the per-page fetch.

Install from the CDN

<script
  src="https://cdn.findip.net/shield/v1.js"
  data-site-key="pub_xxxxxxxxx"
  data-auto-track="true"
  data-privacy-mode="balanced">
</script>

To identify the visitor from a script tag, add data-user-id, data-user-email, data-plan and optionally data-hash-salt. Render them server-side for the logged-in user; the SDK hashes them before sending. Inside a Google Tag Manager Custom HTML tag, call FindIP.init({ siteKey, identify }) with your GTM variables instead, because GTM strips data-* attributes.

The CDN build exposes window.FindIP:

await FindIP.track('login_attempt');
const { sessionId } = FindIP.getSession();

Session ID in your forms

Your server needs the Shield session ID to verify a session. With sessionField the SDK adds it to your forms as a hidden input, so the server does not depend on the _fip_sid cookie (a browser that blocks cookies never has one):

FindIP.init({ siteKey: 'pub_xxxxxxxxx', sessionField: true }); // field name: findip_session

<script src="https://cdn.findip.net/shield/v1.js" data-site-key="pub_xxxxxxxxx" data-session-field="findip_session"></script>

Only forms that POST to the page's own origin get the field. It is off by default.

Keeping a session across links without cookies

For visitors whose browser does not keep the session cookie, linkSession carries the session ID across a link click, including links that open in a new tab:

FindIP.init({ siteKey: 'pub_xxxxxxxxx', linkSession: true });

At click time the SDK adds _fip=<session id>.<time> to same-origin links; the page that opens removes it from the address bar when the SDK starts. It is off by default because it changes link addresses: your server sees the parameter on that one request, and scripts that read the address before the SDK starts can see it. Nothing is added for visitors whose session cookie works.

For reproducible deployments, use a pinned release with SRI instead of the auto-updating v1.js alias.

Version policy

npm and CDN releases use the same SDK semantic version. The mutable v1.js alias serves the latest compatible 1.x SDK, while versioned CDN URLs are immutable and can be verified with SRI.

In-page enforcement

Switch Enforcement on in the site's Settings in the Shield dashboard and the SDK acts on Shield's recommendation for signup, login, checkout, lead and password-reset forms: stop the submit with a message, slow it down with a countdown, ask for a Cloudflare Turnstile challenge that Shield verifies, or redirect blocked visitors. No snippet change is needed; the setting travels inside the /track responses. This is friction against bots and casual abuse that run the page, not a security boundary: confirm sensitive actions on your server with the verify endpoint, which also reports whether the session passed a challenge.

Consent

Shield supports a direct consent API and Google Consent Mode-style storage signals:

setConsent(true);

setConsent({
  security_storage: 'granted',
  analytics_storage: 'denied',
});

Set consentRequired: true when tracking must wait for an explicit decision. See Privacy Modes and Data Collection before deploying.

Documentation

• Quickstart
• JavaScript SDK reference
• Events reference
• Google Tag Manager
• Cookies
• FindIP Threat Network

Development

npm install
npm test
npm run typecheck
npm run lint
npm run build

Build output:

• dist/findip-shield.cjs — CommonJS/UMD bundle
• dist/findip-shield.esm.js — ES module
• dist/findip-shield.min.js — minified browser IIFE
• dist/index.d.ts — TypeScript declarations

Security

Report suspected vulnerabilities privately to [e-mail]. Do not open a public vulnerability report.

License

MIT