Skip to main content
Version: Guardian Web v0.5.0

NPM Package

@surtai/guardian-web · v0.5.0

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:

.npmrc
//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.

warning

Add .npmrc to your .gitignore to avoid committing tokens.

npm install @surtai/guardian-web
Web is collect-only

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.

Durable recognition on Safari

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​

Do not clear 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​

TypeScript
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​

OptionTypeRequiredDefaultDescription
collectLocationbooleanNofalseWhen true, prompts the browser's Geolocation API. The only thing in collect() that can trigger a permission prompt.
geolocationJwtstringNo(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;
}
}
}
CodeMeaning
CRYPTO_UNAVAILABLEwindow.crypto.subtle is missing. The SDK requires a secure context (HTTPS or localhost).
ENCRYPTION_FAILEDThe encryption step failed. Treat as a bug: capture and report.
INVALID_OPTIONSThe 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, localhost for development. The SDK throws CRYPTO_UNAVAILABLE outside a secure context.
  • Geolocation, Battery Status, NetworkInformation, and other optional APIs degrade gracefully when unavailable.

Framework examples​

VerifyButton.tsx
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>
);
}

What's different from the native SDKs​

@surtai/guardian-web@surtai/guardian-rn / iOS / Android
verify() methodNoYes
collect() methodYes (only API)Yes
App-level initializationNoneinitialize(options)
Customer / transaction contextSet by your backendCarried in the backend-minted JWT claims
API key in clientNoNo (uses a backend-minted JWT, not an API key)
Sends the device payload to SurtNo, your backend sends itverify() yes, collect() no
Device integrity checkNo (no browser equivalent)Yes
State kept in the browser or appA per-browser install id in localStorageNo 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.