NPM Package
The @surtai/guardian-web SDK runs Guardian's collect() flow in any modern browser. It gathers device signals, encrypts them in the browser, and returns an opaque payload your backend sends to Surt's evaluate endpoint. collect() does not send the device payload to Surt, and the SDK holds no API key. When you pass an optional geolocationJwt, collect() calls GET /geolocation/client-ip to resolve the browser's public IP and embed it in the payload. The JWT is a token minted by your backend that expires after 30 minutes. It is not an API key.
Install
@surtai/guardian-web is a private npm package. Add your access token to .npmrc in your project root:
//registry.npmjs.org/:_authToken=<YOUR_NPM_TOKEN>
Replace <YOUR_NPM_TOKEN> with the token provided by Surt. This token only installs the package. It is separate from the Surt API key your backend uses.
Add .npmrc to your .gitignore to avoid committing tokens.
npm install @surtai/guardian-web
Unlike the native SDKs (iOS / Android / React Native), the web SDK does not expose a verify() method. All risk decisions happen server-side once your backend forwards the payload. See Collect (Server-to-Server) for the full backend flow.
Device recognition (v0.5.0)
Starting in v0.5.0 the SDK adds two signals to the encrypted payload automatically - no code change on your side:
- Stable device recognition - the SDK mints and persists a per-browser install id and
includes it in
collect(). Surt uses it to recognize a returning device across visits, so the same browser resolves to the same device even when its raw fingerprint collides with other machines of the same model. - SDK version reporting - the SDK reports its own build version, so Surt can attribute each transaction to the exact SDK release.
Both travel inside the encrypted payload - you never read or set them. Upgrading the package is all that is required to benefit; see Migrating v0.4 → v0.5.
Browsers such as Safari evict script-writable storage after ~7 days, which rotates the install id. To keep recognition stable there, your backend can persist the id in a first-party cookie relayed through preflight - an optional, ~5-line change covered in the migration guide.
Keep the SDK's storage
The SDK keeps the install id in localStorage under the key surt_guardian_install_id, and the
network-intelligence signal keeps its own state there too. If your app clears storage on login or
logout, every login becomes a new device. Remove your own keys by name instead of calling
localStorage.clear(), and leave surt_guardian_install_id and any key you did not write in place.
If you cannot avoid a full clear, the first-party cookie relay below is the only thing that keeps
recognition stable.
Usage
import { collect } from '@surtai/guardian-web';
// Variant 1: no IP lookup.
const { payload } = await collect({ collectLocation: false });
// Variant 2: resolve the browser's public IP into the payload.
// Your backend mints the short-lived JWT via preflight.
const { payload: payloadWithIp } = await collect({
collectLocation: false,
geolocationJwt: jwt,
});
// Forward the payload to your backend.
await fetch('https://your-api.com/verify-device', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ userId: 'user_123', payload }),
});
Your backend mints the geolocationJwt by calling preflight with your sp_live_* key. See Authentication. Pass the JWT to collect() when you want the public IP resolved or when you relay the install id through a first-party cookie. Request a new JWT for each transaction. A JWT expires 30 minutes after it is issued.
Options
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
collectLocation | boolean | No | false | When true, prompts the browser's Geolocation API. The only thing in collect() that can trigger a permission prompt. |
geolocationJwt | string | No | (none) | When provided, collect() resolves the browser's public IP via GET /geolocation/client-ip and embeds it in the payload. Omit it to skip the IP lookup. |
CollectResult
interface CollectResult {
/** Base64 payload. Pass as `payload.data` in the evaluate request shown below. */
payload: string;
/** What the SDK observed while collecting. Safe to ignore. */
diagnostics: {
location?: 'collected' | 'denied' | 'unavailable' | 'timeout' | 'not_requested' | 'error';
networkIntel?: 'collected' | 'unavailable' | 'not_requested';
warnings: { code: string; signal: string; detail?: string }[];
};
}
The diagnostics object tells you what happened on-device - for example whether location was collected or the user denied it - so you can react in your UI:
const { payload, diagnostics } = await collect({ collectLocation: true });
if (diagnostics.location === 'denied') {
// prompt the user to enable location, then retry
}
See Result diagnostics for the meaning of each value and the warning codes. The web SDK does not return attestation or timings.
Backend: forward to Surt
Your backend receives the payload from the browser and posts to Surt's evaluate endpoint:
POST https://api.surt.com/geolocation/transactions/evaluate
Content-Type: application/json
Authorization: Bearer YOUR_SURT_API_KEY
{
"customer_id": "user_123",
"transaction_type": "login",
"transaction_name": "Sign in",
"payload": {
"type": "encrypted",
"data": "<payload from collect()>"
},
"config": {
"response": {
"address": { "type": "include" }
}
}
}
The request shape, transaction_type values, config options, and response schema are the same for every Guardian SDK. Only transaction_type and payload are required. See Collect (Server-to-Server) for the complete reference, including the optional event_id for safe retries and Node / Java / Python examples.
Errors
collect() throws a single GuardianError for three conditions:
import { collect, GuardianError } from '@surtai/guardian-web';
try {
const { payload } = await collect();
} catch (err) {
if (err instanceof GuardianError) {
switch (err.code) {
case 'CRYPTO_UNAVAILABLE': /* not in a secure context */ break;
case 'ENCRYPTION_FAILED': /* encryption failed (rare) */ break;
case 'INVALID_OPTIONS': /* bad arguments */ break;
}
}
}
| Code | Meaning |
|---|---|
CRYPTO_UNAVAILABLE | window.crypto.subtle is missing. The SDK requires a secure context (HTTPS or localhost). |
ENCRYPTION_FAILED | The encryption step failed. Treat as a bug: capture and report. |
INVALID_OPTIONS | The argument to collect() is not an object. |
Individual collectors (fingerprint, battery, geolocation, network, etc.) never throw: they fail soft. A revoked permission or unsupported API just means the corresponding field is omitted from the payload. The public-IP lookup is also best-effort: if the GET /geolocation/client-ip call fails or the JWT is rejected, the IP field is simply omitted and collect() still returns a payload. The backend tolerates sparse payloads.
Browser support
- Any evergreen browser with
window.crypto.subtle(Chrome, Edge, Firefox, Safari, Opera). - Secure context required: HTTPS in production,
localhostfor development. The SDK throwsCRYPTO_UNAVAILABLEoutside a secure context. - Geolocation, Battery Status, NetworkInformation, and other optional APIs degrade gracefully when unavailable.
Framework examples
- React
- Next.js
- Vue
- Svelte
- Vanilla JS
import { useState } from 'react';
import { collect } from '@surtai/guardian-web';
export function VerifyButton({ userId }: { userId: string }) {
const [loading, setLoading] = useState(false);
const handleClick = async () => {
setLoading(true);
try {
const { payload } = await collect({ collectLocation: false });
await fetch('/api/verify-device', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ userId, payload }),
});
} finally {
setLoading(false);
}
};
return (
<button onClick={handleClick} disabled={loading}>
{loading ? 'Verifying...' : 'Continue'}
</button>
);
}
'use client';
import { collect } from '@surtai/guardian-web';
export function SignInForm() {
async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
e.preventDefault();
const { payload } = await collect();
await fetch('/api/sign-in', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: new FormData(e.currentTarget).get('email'),
payload,
}),
});
// Your /api/sign-in route forwards `payload` to Surt's /evaluate.
}
return (
<form onSubmit={handleSubmit}>
<input name="email" type="email" required />
<button type="submit">Sign in</button>
</form>
);
}
<script setup lang="ts">
import { ref } from 'vue';
import { collect } from '@surtai/guardian-web';
const loading = ref(false);
const props = defineProps<{ userId: string }>();
async function verify() {
loading.value = true;
try {
const { payload } = await collect();
await fetch('/api/verify-device', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ userId: props.userId, payload }),
});
} finally {
loading.value = false;
}
}
</script>
<template>
<button :disabled="loading" @click="verify">
{{ loading ? 'Verifying...' : 'Continue' }}
</button>
</template>
<script>
import { collect } from '@surtai/guardian-web';
export let userId;
let loading = false;
async function verify() {
loading = true;
try {
const { payload } = await collect();
await fetch('/api/verify-device', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ userId, payload }),
});
} finally {
loading = false;
}
}
</script>
<button on:click={verify} disabled={loading}>
{loading ? 'Verifying...' : 'Continue'}
</button>
<button id="verify">Continue</button>
<script type="module" src="./main.js"></script>
import { collect } from '@surtai/guardian-web';
document.getElementById('verify').addEventListener('click', async () => {
const { payload } = await collect({ collectLocation: false });
await fetch('/api/verify-device', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ userId: 'user_123', payload }),
});
});
The package is private, so a public CDN cannot serve it. Install it from npm and build main.js with a bundler such as Vite, webpack, or esbuild.
What's different from the native SDKs
@surtai/guardian-web | @surtai/guardian-rn / iOS / Android | |
|---|---|---|
verify() method | No | Yes |
collect() method | Yes (only API) | Yes |
| App-level initialization | None | initialize(options) |
| Customer / transaction context | Set by your backend | Carried in the backend-minted JWT claims |
| API key in client | No | No (uses a backend-minted JWT, not an API key) |
| Sends the device payload to Surt | No, your backend sends it | verify() yes, collect() no |
| Device integrity check | No (no browser equivalent) | Yes |
| State kept in the browser or app | A per-browser install id in localStorage | No per-customer state |
Web is intentionally lean: a single static function that produces an encrypted payload. Customer binding, transaction metadata, and decisions all happen in your backend.