zeno.id 0.3.1 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -2
- package/dist/server/index.cjs +37 -6
- package/dist/server/index.d.cts +171 -33
- package/dist/server/index.d.ts +171 -33
- package/dist/server/index.js +37 -6
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -12,7 +12,7 @@ One package for the browser and the server. `zeno.id/server` holds your API key,
|
|
|
12
12
|
|
|
13
13
|
## How it fits together
|
|
14
14
|
|
|
15
|
-
1. Make a project and an API key in the
|
|
15
|
+
1. Make a project and an API key in the app, and put the key in your server's environment:
|
|
16
16
|
|
|
17
17
|
```sh
|
|
18
18
|
ZENO_API_KEY=sk_...
|
|
@@ -232,7 +232,9 @@ app.all('/zeno', nodeHandler(zeno)) // the path you chose
|
|
|
232
232
|
import { zeno } from '@/lib/zeno'
|
|
233
233
|
|
|
234
234
|
// X-Real-IP: set by Vercel, or by your own proxy (nginx: proxy_set_header X-Real-IP $remote_addr;)
|
|
235
|
-
const handler = (request: Request) =>
|
|
235
|
+
const handler = (request: Request) => {
|
|
236
|
+
return zeno(request, request.headers.get('x-real-ip'))
|
|
237
|
+
}
|
|
236
238
|
|
|
237
239
|
// Next.js calls the export named after the method
|
|
238
240
|
export const GET = handler
|
|
@@ -367,6 +369,7 @@ const { url } = await client.createEmbed({
|
|
|
367
369
|
| `getVisitor(visitorId)` | `GET /visitors/{visitorId}` |
|
|
368
370
|
| `deleteVisitor(visitorId)` | `DELETE /visitors/{visitorId}` |
|
|
369
371
|
| `deleteExternalId(externalId)` | `DELETE /external-ids?externalId=...` |
|
|
372
|
+
| `reportOutcome(requestId, outcome)` | `POST /outcomes`, `fraud` or `legitimate`, the latest counts |
|
|
370
373
|
| `addRelation({ externalId, type, value or relatedExternalId, action?, at? })` | `POST /related` |
|
|
371
374
|
| `removeRelation({ externalId, type, value or relatedExternalId })` | `DELETE /related?externalId=...&type=...`, `{ removed }`, free |
|
|
372
375
|
| `getRelated(externalId, { type?, depth? })` | `GET /related?externalId=...`, every type unless `type` names one |
|
package/dist/server/index.cjs
CHANGED
|
@@ -43,6 +43,21 @@ const isIpMismatch = (eventIp, ip) => {
|
|
|
43
43
|
const requestIp = ip.trim();
|
|
44
44
|
return eventIp.includes(":") === requestIp.includes(":") && networkOf(eventIp) !== networkOf(requestIp);
|
|
45
45
|
};
|
|
46
|
+
const isNestedDeeperThan = (text, max) => {
|
|
47
|
+
let depth = 0;
|
|
48
|
+
let isInString = false;
|
|
49
|
+
for (let index = 0; index < text.length; index++) {
|
|
50
|
+
const char = text[index];
|
|
51
|
+
if (isInString) {
|
|
52
|
+
if (char === "\\") index++;
|
|
53
|
+
else if (char === "\"") isInString = false;
|
|
54
|
+
} else if (char === "\"") isInString = true;
|
|
55
|
+
else if (char === "{" || char === "[") {
|
|
56
|
+
if (++depth > max) return true;
|
|
57
|
+
} else if (char === "}" || char === "]") depth--;
|
|
58
|
+
}
|
|
59
|
+
return false;
|
|
60
|
+
};
|
|
46
61
|
//#endregion
|
|
47
62
|
//#region src/server/proxy.ts
|
|
48
63
|
const isStrings = (value) => {
|
|
@@ -54,6 +69,7 @@ const rawHeadersOf = (internal) => {
|
|
|
54
69
|
};
|
|
55
70
|
const COOKIE = "zeno_id";
|
|
56
71
|
const MAX_BODY = 131072;
|
|
72
|
+
const MAX_NESTING = 64;
|
|
57
73
|
const TIMEOUT$1 = 1e4;
|
|
58
74
|
const jsonResponse = (status, body, headers = {}) => {
|
|
59
75
|
return new Response(JSON.stringify(body), {
|
|
@@ -284,9 +300,10 @@ const createProxy = (apiKey, options = {}) => {
|
|
|
284
300
|
};
|
|
285
301
|
const handlePost = async (request, ip, internal) => {
|
|
286
302
|
if (!/^application\/json\s*(;|$)/i.test(request.headers.get("content-type") ?? "")) return invalidRequest("The body must be JSON");
|
|
287
|
-
if (request.headers.get("sec-fetch-site") === "cross-site") return invalidRequest("Cross-site requests are refused");
|
|
303
|
+
if (request.headers.get("sec-fetch-site")?.toLowerCase() === "cross-site") return invalidRequest("Cross-site requests are refused");
|
|
288
304
|
const bodyText = await readCappedBody(request, MAX_BODY);
|
|
289
305
|
if (bodyText === void 0) return invalidRequest("The body is larger than 128 KB");
|
|
306
|
+
if (isNestedDeeperThan(bodyText, MAX_NESTING)) return invalidRequest(`The body nests deeper than ${MAX_NESTING} levels`);
|
|
290
307
|
let payload;
|
|
291
308
|
try {
|
|
292
309
|
payload = JSON.parse(bodyText);
|
|
@@ -380,6 +397,7 @@ const SIGNALS = [
|
|
|
380
397
|
"ai-agent",
|
|
381
398
|
"privacy-browser",
|
|
382
399
|
"rare-device",
|
|
400
|
+
"high-activity",
|
|
383
401
|
"replayed",
|
|
384
402
|
"residential-proxy",
|
|
385
403
|
"private-relay",
|
|
@@ -431,7 +449,7 @@ const defineShape = (name, fields) => ({
|
|
|
431
449
|
const EVENT = defineShape("an event", {
|
|
432
450
|
requestId: "string",
|
|
433
451
|
visitorId: "string",
|
|
434
|
-
ip: "
|
|
452
|
+
ip: "object",
|
|
435
453
|
createdAt: "string",
|
|
436
454
|
riskScore: "number",
|
|
437
455
|
signals: "object",
|
|
@@ -444,6 +462,10 @@ const VISITOR = defineShape("a visitor", {
|
|
|
444
462
|
externalIdCount: "number",
|
|
445
463
|
recentEvents: "array"
|
|
446
464
|
});
|
|
465
|
+
const REPORTED_OUTCOME = defineShape("a reported outcome", {
|
|
466
|
+
requestId: "string",
|
|
467
|
+
outcome: "string"
|
|
468
|
+
});
|
|
447
469
|
const DELETED_VISITOR = defineShape("an erasure", {
|
|
448
470
|
visitorId: "string",
|
|
449
471
|
deletedEvents: "number"
|
|
@@ -582,7 +604,16 @@ const createClient = (apiKey, options = {}) => {
|
|
|
582
604
|
},
|
|
583
605
|
/** A visitor (a browser) with every external id seen with it. */
|
|
584
606
|
getVisitor: async (visitorId) => callApi("GET", `/visitors/${toPathSegment("visitorId", visitorId)}`, VISITOR),
|
|
585
|
-
/**
|
|
607
|
+
/**
|
|
608
|
+
* Reports what an event turned out to be, like after a chargeback or a review. The latest report counts, and it
|
|
609
|
+
* never changes the event's score.
|
|
610
|
+
*/
|
|
611
|
+
reportOutcome: (requestId, outcome) => {
|
|
612
|
+
return callApi("POST", "/outcomes", REPORTED_OUTCOME, {
|
|
613
|
+
requestId,
|
|
614
|
+
outcome
|
|
615
|
+
});
|
|
616
|
+
},
|
|
586
617
|
deleteVisitor: async (visitorId) => {
|
|
587
618
|
return callApi("DELETE", `/visitors/${toPathSegment("visitorId", visitorId)}`, DELETED_VISITOR);
|
|
588
619
|
},
|
|
@@ -718,8 +749,8 @@ const MISSING_KEY = "unsealResult needs the project's encryption key as key (is
|
|
|
718
749
|
const keyBytesOf = (secret) => {
|
|
719
750
|
const trimmedKey = requireSecret(secret, MISSING_KEY).trim();
|
|
720
751
|
const keyBytes = /^[A-Za-z0-9+/]+={0,2}$/.test(trimmedKey) ? fromBase64(trimmedKey) : void 0;
|
|
721
|
-
if (!keyBytes) throw new TypeError("unsealResult's key isn't base64: pass the project's encryption key as the
|
|
722
|
-
if (keyBytes.length !== 32) throw new TypeError(/^[0-9a-f]{64}$/i.test(trimmedKey) ? "unsealResult's key looks like hex: pass the project's encryption key as the
|
|
752
|
+
if (!keyBytes) throw new TypeError("unsealResult's key isn't base64: pass the project's encryption key as the app shows it");
|
|
753
|
+
if (keyBytes.length !== 32) throw new TypeError(/^[0-9a-f]{64}$/i.test(trimmedKey) ? "unsealResult's key looks like hex: pass the project's encryption key as the app shows it, in base64" : `unsealResult's key is ${keyBytes.length} bytes, not 32: pass the project's encryption key as the app shows it`);
|
|
723
754
|
return keyBytes;
|
|
724
755
|
};
|
|
725
756
|
const decryptWithAnyKey = async (keys, data) => {
|
|
@@ -764,7 +795,7 @@ const unsealResult = async (sealed, options) => {
|
|
|
764
795
|
if (!EVENT.is(event)) throw new Error("The sealed result opened but isn't an event; update zeno.id/server");
|
|
765
796
|
const failedChecks = [];
|
|
766
797
|
const maxAge = options.maxAge ?? UNSEAL_MAX_AGE;
|
|
767
|
-
if (options.ip && isIpMismatch(event.ip, options.ip)) failedChecks.push("ip-mismatch");
|
|
798
|
+
if (options.ip && isIpMismatch(event.ip.address, options.ip)) failedChecks.push("ip-mismatch");
|
|
768
799
|
if (Date.now() - Date.parse(event.createdAt) > maxAge * 1e3) failedChecks.push("too-old");
|
|
769
800
|
if (options.externalId !== void 0 && event.externalId !== void 0 && event.externalId !== options.externalId) failedChecks.push("external-id-mismatch");
|
|
770
801
|
if (failedChecks.length > 0) return {
|
package/dist/server/index.d.cts
CHANGED
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
import { a as ApiOptions, i as ApiKey, n as ProxyOptions, r as createProxy, t as ProxyHandler } from "./proxy-CUZ-Jwgy.cjs";
|
|
2
2
|
//#region src/server/index.d.ts
|
|
3
3
|
/** Every signal an event checks, the keys of its `signals`. */
|
|
4
|
-
declare const SIGNALS: readonly ['automation', 'headless', 'software-renderer', 'tampering', 'timezone-mismatch', 'privacy-settings', 'vpn', 'proxy', 'tor', 'datacenter', 'abusive-ip', 'incognito', 'virtual-machine', 'developer-tools', 'ai-agent', 'privacy-browser', 'rare-device', 'replayed', 'residential-proxy', 'private-relay', 'forged-payload', 'stored-id-rejected'];
|
|
4
|
+
declare const SIGNALS: readonly ['automation', 'headless', 'software-renderer', 'tampering', 'timezone-mismatch', 'privacy-settings', 'vpn', 'proxy', 'tor', 'datacenter', 'abusive-ip', 'incognito', 'virtual-machine', 'developer-tools', 'ai-agent', 'privacy-browser', 'rare-device', 'high-activity', 'replayed', 'residential-proxy', 'private-relay', 'forged-payload', 'stored-id-rejected'];
|
|
5
5
|
type Signal = (typeof SIGNALS)[number];
|
|
6
6
|
/** The bot verdict: a known good bot (a search engine's crawler), a bad one (automation, a headless browser), or none. */
|
|
7
7
|
type Bot = 'good' | 'bad' | 'not-detected';
|
|
8
8
|
/**
|
|
9
9
|
* Why a signal's `detected` is `null`: what it reads was missing, so it couldn't be checked. The ip lookup failed or
|
|
10
10
|
* took too long; the browser or the connection gave no time zone; a browser probe timed out, failed or wasn't reported;
|
|
11
|
-
* Chromium's static storage quota, the same in normal and private windows; no WebGL or canvas;
|
|
12
|
-
*
|
|
11
|
+
* Chromium's static storage quota, the same in normal and private windows; no WebGL or canvas; too few devices were
|
|
12
|
+
* seen yet to call hardware rare; the request carried no nonce.
|
|
13
13
|
*/
|
|
14
14
|
type SignalReason = 'ip-lookup-failed' | 'ip-lookup-timeout' | 'no-time-zone' | 'no-ip-time-zone' | 'probe-timeout' | 'probe-failed' | 'not-collected' | 'no-webgl' | 'no-canvas' | 'too-few-visitors' | 'no-nonce';
|
|
15
15
|
type Confidence = 'high' | 'medium' | 'low';
|
|
@@ -38,10 +38,109 @@ type Velocity = {
|
|
|
38
38
|
distinctIpByExternalId: number;
|
|
39
39
|
distinctVisitorIdByExternalId: number;
|
|
40
40
|
};
|
|
41
|
+
/**
|
|
42
|
+
* What's global about an event, up to the event: its device and ip across every project using Zeno, as numbers and
|
|
43
|
+
* coarse network facts. Only on getEvent and verify; none when the project turned it off.
|
|
44
|
+
*/
|
|
45
|
+
type GlobalFields = {
|
|
46
|
+
/** The device's history across every project, from its latest 1,000 events. */
|
|
47
|
+
history?: {
|
|
48
|
+
/** The month any project first saw the device, among the events still kept. */
|
|
49
|
+
firstSeenAt?: string;
|
|
50
|
+
events: number;
|
|
51
|
+
/** Its events' risk scores; the event's own `riskScore` is this request's. */
|
|
52
|
+
riskScore: {
|
|
53
|
+
highest: number;
|
|
54
|
+
average: number;
|
|
55
|
+
};
|
|
56
|
+
badBotEvents: number;
|
|
57
|
+
/**
|
|
58
|
+
* The visitor's latest residential connections in your project, up to 10, newest first. Never another
|
|
59
|
+
* project's.
|
|
60
|
+
*/
|
|
61
|
+
residentialIps: EventIp[];
|
|
62
|
+
/**
|
|
63
|
+
* The device's residential networks on every project, up to 10, latest first. Never an address or what locates
|
|
64
|
+
* someone.
|
|
65
|
+
*/
|
|
66
|
+
residentialNetworks: Omit<EventIp, 'address' | 'city' | 'postalCode' | 'latitude' | 'longitude' | 'locationAccuracy' | 'networkRange'>[];
|
|
67
|
+
};
|
|
68
|
+
globalVelocity?: Record<'5m' | '1h' | '24h', Pick<Velocity, 'events' | 'distinctIp' | 'distinctExternalId' | 'distinctCountry'> & {
|
|
69
|
+
/** Every device's events from the event's ip, on every project. */
|
|
70
|
+
ipEvents: number;
|
|
71
|
+
}>;
|
|
72
|
+
};
|
|
73
|
+
/**
|
|
74
|
+
* What the browser reported. Values that could identify a device on their own are hashes of your project's own, so you
|
|
75
|
+
* can compare your events, but they never match another project's; ones many devices share, like the screen, are as
|
|
76
|
+
* reported. Each is left out when the browser didn't report it.
|
|
77
|
+
*/
|
|
78
|
+
type RawDeviceAttributes = {
|
|
79
|
+
canvas?: string;
|
|
80
|
+
canvasText?: string;
|
|
81
|
+
audio?: string;
|
|
82
|
+
webgl?: {
|
|
83
|
+
vendor: string;
|
|
84
|
+
renderer: string;
|
|
85
|
+
extensions: string;
|
|
86
|
+
parameters: string;
|
|
87
|
+
};
|
|
88
|
+
screen?: {
|
|
89
|
+
width: number;
|
|
90
|
+
height: number;
|
|
91
|
+
colorDepth: number;
|
|
92
|
+
pixelRatio: number;
|
|
93
|
+
};
|
|
94
|
+
hardwareConcurrency?: number;
|
|
95
|
+
deviceMemory?: number;
|
|
96
|
+
maxTouchPoints?: number;
|
|
97
|
+
platform?: string;
|
|
98
|
+
architecture?: number;
|
|
99
|
+
vendor?: string;
|
|
100
|
+
oscpu?: string;
|
|
101
|
+
deviceModel?: string;
|
|
102
|
+
timeZone?: string;
|
|
103
|
+
timezoneOffsets?: number[];
|
|
104
|
+
languages?: string[];
|
|
105
|
+
dateTimeLocale?: string;
|
|
106
|
+
cookies?: boolean;
|
|
107
|
+
localStorage?: boolean;
|
|
108
|
+
sessionStorage?: boolean;
|
|
109
|
+
indexedDb?: boolean;
|
|
110
|
+
plugins?: string;
|
|
111
|
+
fonts?: string;
|
|
112
|
+
emoji?: string;
|
|
113
|
+
fontPreferences?: string;
|
|
114
|
+
math?: string;
|
|
115
|
+
keyboard?: string;
|
|
116
|
+
};
|
|
117
|
+
/** What an event turned out to be, as your backend reports it. */
|
|
118
|
+
type Outcome = 'fraud' | 'legitimate';
|
|
119
|
+
/** What kind of bot an event was. */
|
|
120
|
+
type BotType = 'automation' | 'replayed' | 'forged-request' | 'fake-crawler' | 'crawler' | 'ai-agent';
|
|
121
|
+
/** The bot verdict, and what's known of the bot. */
|
|
122
|
+
type EventBot = {
|
|
123
|
+
result: Bot;
|
|
124
|
+
/** Absent when no bot was detected. */
|
|
125
|
+
type?: BotType;
|
|
126
|
+
/** How sure the type is: `low` for an AI agent that only says what it is. */
|
|
127
|
+
confidence?: Confidence;
|
|
128
|
+
/** Who runs it, like `Google`, when it gives a name we know. */
|
|
129
|
+
provider?: string;
|
|
130
|
+
/** The name it goes by, like `Googlebot`, when it gives one. */
|
|
131
|
+
name?: string;
|
|
132
|
+
/** Whether its network confirmed that name: true for a real crawler, false for one pretending. */
|
|
133
|
+
verified?: boolean;
|
|
134
|
+
};
|
|
41
135
|
/** What owns an ip address or runs its network. */
|
|
42
136
|
type NetworkOwnerType = 'isp' | 'hosting' | 'business' | 'education' | 'government' | 'banking';
|
|
43
|
-
/**
|
|
44
|
-
|
|
137
|
+
/**
|
|
138
|
+
* The connection: its ip address and, from the ip lookup, who owns it and where it is. Only the address when the lookup
|
|
139
|
+
* failed.
|
|
140
|
+
*/
|
|
141
|
+
type EventIp = {
|
|
142
|
+
/** The ip address, as the proxy route passed it. Behind a VPN or proxy, the exit's. */
|
|
143
|
+
address: string;
|
|
45
144
|
/** The country's two-letter code, like `US`. */
|
|
46
145
|
country?: string;
|
|
47
146
|
countryName?: string;
|
|
@@ -85,18 +184,32 @@ type IpInfo = {
|
|
|
85
184
|
/** A private or reserved address that no one on the internet has. */
|
|
86
185
|
reservedAddress: boolean;
|
|
87
186
|
};
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
187
|
+
/** The browser, parsed on the server from the user agent and client hints. */
|
|
188
|
+
type EventBrowser = {
|
|
189
|
+
name: string;
|
|
190
|
+
/** The major version, like `157`. */
|
|
191
|
+
version?: string;
|
|
192
|
+
fullVersion?: string;
|
|
92
193
|
os: string;
|
|
93
194
|
osVersion?: string;
|
|
94
195
|
device: string;
|
|
196
|
+
/** The browser's user agent string, as it sent it. */
|
|
197
|
+
userAgent: string;
|
|
95
198
|
};
|
|
96
199
|
/** What some signals found, on their entry in `signals` when they're detected, each field only when there was one. */
|
|
97
200
|
type SignalDetails = {
|
|
98
201
|
vpn: {
|
|
99
202
|
confidence?: Confidence;
|
|
203
|
+
/** Why it's a VPN: a known exit, iCloud Private Relay or a time zone that doesn't fit. */
|
|
204
|
+
methods?: {
|
|
205
|
+
knownVpnExit: boolean;
|
|
206
|
+
privateRelay: boolean;
|
|
207
|
+
timeZoneMismatch: boolean;
|
|
208
|
+
};
|
|
209
|
+
/** The browser's own time zone, likely where the person really is. */
|
|
210
|
+
originTimeZone?: string;
|
|
211
|
+
/** The country of that time zone, like `DE`: a hint, not proof. */
|
|
212
|
+
originCountry?: string;
|
|
100
213
|
};
|
|
101
214
|
proxy: {
|
|
102
215
|
confidence?: Confidence;
|
|
@@ -164,7 +277,7 @@ type Event = {
|
|
|
164
277
|
verdict: Verdict;
|
|
165
278
|
/** 0 to 30: the detected signals' points, capped at 30. */
|
|
166
279
|
riskScore: number;
|
|
167
|
-
bot:
|
|
280
|
+
bot: EventBot;
|
|
168
281
|
/** How sure the visitor id is, 0.1 to 1. */
|
|
169
282
|
confidence: number;
|
|
170
283
|
/**
|
|
@@ -180,28 +293,40 @@ type Event = {
|
|
|
180
293
|
/** The id of the API key whose proxy route identified (search filters on it as `apiKeyId`). */
|
|
181
294
|
apiKeyId: string;
|
|
182
295
|
createdAt: string;
|
|
183
|
-
/**
|
|
296
|
+
/**
|
|
297
|
+
* When `verify` attached its external id or an outcome was reported afterwards; that also sends an `update`
|
|
298
|
+
* webhook.
|
|
299
|
+
*/
|
|
184
300
|
updatedAt?: string;
|
|
185
|
-
/** When the project's retention removes it (ISO), 3 years after the event at most. Not in search results. */
|
|
186
|
-
expiresAt?: string;
|
|
187
301
|
origin?: string;
|
|
188
302
|
/** The page as origin and path, or only its origin; left out when the project keeps no page urls (`pageUrls`). */
|
|
189
303
|
url?: string;
|
|
190
304
|
referrer?: string;
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
browserDetails: BrowserDetails;
|
|
194
|
-
ip: string;
|
|
195
|
-
/** Who owns the ip and where it is, with its `country` and `timeZone`; none when the lookup failed. */
|
|
196
|
-
ipInfo?: IpInfo;
|
|
305
|
+
browser: EventBrowser;
|
|
306
|
+
ip: EventIp;
|
|
197
307
|
/**
|
|
198
308
|
* Every signal Zeno checks: `detected` true, false, or null when it couldn't be checked (with a `reason`), the
|
|
199
309
|
* `points` a detected one added, and what it found. Read `event.signals.vpn.detected`.
|
|
200
310
|
*/
|
|
201
311
|
signals: Signals;
|
|
312
|
+
/** What your backend reported the event turned out to be (`reportOutcome`). */
|
|
313
|
+
outcome?: Outcome;
|
|
314
|
+
/** A looser id than `visitorId`: the hardware alone, shared by identical devices. Only on getEvent and verify. */
|
|
315
|
+
broadVisitorId?: string;
|
|
316
|
+
/**
|
|
317
|
+
* The approximate area, as an id per project, with a radius in km. None behind a VPN or proxy. Only on getEvent and
|
|
318
|
+
* verify.
|
|
319
|
+
*/
|
|
320
|
+
proximity?: {
|
|
321
|
+
id: string;
|
|
322
|
+
radius: number;
|
|
323
|
+
confidence: number;
|
|
324
|
+
};
|
|
325
|
+
/** Only on getEvent and verify, not in webhooks or sealed results. */
|
|
326
|
+
rawDeviceAttributes?: RawDeviceAttributes;
|
|
202
327
|
/** Only on getEvent and verify, not in webhooks or sealed results. */
|
|
203
328
|
velocity?: Record<'5m' | '1h' | '24h', Velocity>;
|
|
204
|
-
};
|
|
329
|
+
} & GlobalFields;
|
|
205
330
|
/** A list filter takes one value, or several to match any of. */
|
|
206
331
|
type AnyOf<T> = T | T[];
|
|
207
332
|
type SearchFilters = {
|
|
@@ -219,6 +344,8 @@ type SearchFilters = {
|
|
|
219
344
|
action?: AnyOf<string>;
|
|
220
345
|
signal?: AnyOf<Signal>;
|
|
221
346
|
bot?: AnyOf<Bot>;
|
|
347
|
+
/** What your backend reported, among the events with a report. */
|
|
348
|
+
outcome?: AnyOf<Outcome>;
|
|
222
349
|
minRiskScore?: number;
|
|
223
350
|
/**
|
|
224
351
|
* Inclusive. Without it the search covers the 30 days before `end` (or now), unless it looks up a `visitorId`,
|
|
@@ -232,16 +359,17 @@ type SearchFilters = {
|
|
|
232
359
|
};
|
|
233
360
|
/**
|
|
234
361
|
* An event as the search lists it: a subset of the event's own fields, with the same names. It leaves out `returning`,
|
|
235
|
-
* `metadata`, `updatedAt`, `
|
|
236
|
-
*
|
|
237
|
-
* version, and its `
|
|
362
|
+
* `metadata`, `updatedAt`, `url`, `referrer` and `velocity`; its `signals` list only the detected ones, as `{ detected:
|
|
363
|
+
* true }` (get the event for the rest), its `browser` holds the user agent, and the browser's and the os's name and
|
|
364
|
+
* version, and its `ip` the address with the country, city, asn and company, each left out when the event has none of
|
|
365
|
+
* them.
|
|
238
366
|
*/
|
|
239
|
-
type SearchEvent = Pick<Event, 'requestId' | 'visitorId' | 'verdict' | 'riskScore' | 'bot' | 'confidence' | 'externalId' | 'action' | 'apiKeyId' | 'createdAt' | 'origin'
|
|
367
|
+
type SearchEvent = Pick<Event, 'requestId' | 'visitorId' | 'verdict' | 'riskScore' | 'bot' | 'outcome' | 'confidence' | 'externalId' | 'action' | 'apiKeyId' | 'createdAt' | 'origin'> & {
|
|
240
368
|
signals: { [S in Signal]?: {
|
|
241
369
|
detected: true;
|
|
242
370
|
}; };
|
|
243
|
-
|
|
244
|
-
|
|
371
|
+
browser: Pick<EventBrowser, 'userAgent'> & Partial<Pick<EventBrowser, 'name' | 'version' | 'os' | 'osVersion'>>;
|
|
372
|
+
ip: Pick<EventIp, 'address' | 'country' | 'city' | 'asn' | 'company'>;
|
|
245
373
|
};
|
|
246
374
|
/** A page of a list: pass `cursor` back for the next one; none on the last. */
|
|
247
375
|
type Page<T> = {
|
|
@@ -258,7 +386,7 @@ type SearchResult = Page<SearchEvent> & {
|
|
|
258
386
|
/**
|
|
259
387
|
* A visitor: `externalIds` the latest 10 external ids seen with it, newest first, and `externalIdCount` how many there
|
|
260
388
|
* are in all; `signals` holds every signal any of its events detected, as `{ detected: true }`, and `recentEvents` its
|
|
261
|
-
* 20 latest events, newest first, each with its detected signals the same way and `
|
|
389
|
+
* 20 latest events, newest first, each with its detected signals the same way and `ip.country` when known.
|
|
262
390
|
*/
|
|
263
391
|
type Visitor = {
|
|
264
392
|
visitorId: string;
|
|
@@ -270,8 +398,8 @@ type Visitor = {
|
|
|
270
398
|
eventCount: number;
|
|
271
399
|
firstSeenAt: string;
|
|
272
400
|
lastSeenAt: string;
|
|
273
|
-
recentEvents: (Pick<SearchEvent, 'requestId' | 'externalId' | 'createdAt' | '
|
|
274
|
-
|
|
401
|
+
recentEvents: (Pick<SearchEvent, 'requestId' | 'externalId' | 'createdAt' | 'signals'> & {
|
|
402
|
+
ip: Pick<EventIp, 'address' | 'country'>;
|
|
275
403
|
})[];
|
|
276
404
|
};
|
|
277
405
|
/**
|
|
@@ -350,7 +478,10 @@ type RelatedUser = {
|
|
|
350
478
|
externalId: string;
|
|
351
479
|
createdAt: string;
|
|
352
480
|
};
|
|
353
|
-
/**
|
|
481
|
+
/**
|
|
482
|
+
* A value more than one user shares, or for a relation type the two users it ties; `count` is how many users share it
|
|
483
|
+
* (2 for a relation).
|
|
484
|
+
*/
|
|
354
485
|
type SharedValue = {
|
|
355
486
|
type: RelatedType;
|
|
356
487
|
weight: number;
|
|
@@ -505,7 +636,14 @@ declare const createClient: (apiKey: ApiKey, options?: ClientOptions) => {
|
|
|
505
636
|
searchEvents: (filters?: SearchFilters) => Promise<SearchResult>;
|
|
506
637
|
/** A visitor (a browser) with every external id seen with it. */
|
|
507
638
|
getVisitor: (visitorId: string) => Promise<Visitor>;
|
|
508
|
-
/**
|
|
639
|
+
/**
|
|
640
|
+
* Reports what an event turned out to be, like after a chargeback or a review. The latest report counts, and it
|
|
641
|
+
* never changes the event's score.
|
|
642
|
+
*/
|
|
643
|
+
reportOutcome: (requestId: string, outcome: Outcome) => Promise<{
|
|
644
|
+
requestId: string;
|
|
645
|
+
outcome: Outcome;
|
|
646
|
+
}>;
|
|
509
647
|
deleteVisitor: (visitorId: string) => Promise<{
|
|
510
648
|
visitorId: string;
|
|
511
649
|
deletedEvents: number;
|
|
@@ -576,7 +714,7 @@ declare const createClient: (apiKey: ApiKey, options?: ClientOptions) => {
|
|
|
576
714
|
/** The client `createClient` makes. */
|
|
577
715
|
type Client = ReturnType<typeof createClient>;
|
|
578
716
|
/** A webhook delivery's body: the event, without its velocity. */
|
|
579
|
-
type WebhookEvent = Omit<Event, 'velocity'>;
|
|
717
|
+
type WebhookEvent = Omit<Event, 'broadVisitorId' | 'proximity' | 'rawDeviceAttributes' | 'velocity' | keyof GlobalFields>;
|
|
580
718
|
/**
|
|
581
719
|
* Checks a webhook delivery's Zeno-Signature header against the project's webhook secret, and that it was signed in the
|
|
582
720
|
* last `tolerance` seconds, so a captured delivery can't be replayed later. Pass the raw body. Resolves to the event
|
|
@@ -615,4 +753,4 @@ type UnsealOptions = {
|
|
|
615
753
|
*/
|
|
616
754
|
declare const unsealResult: (sealed: string | undefined | null, options: UnsealOptions) => Promise<VerifyResult>;
|
|
617
755
|
//#endregion
|
|
618
|
-
export { AddedRelation, type ApiOptions, Bot,
|
|
756
|
+
export { AddedRelation, type ApiOptions, Bot, BotType, Client, ClientOptions, Confidence, Connection, Contradiction, Embed, Event, EventBot, EventBrowser, EventIp, ForgedPayloadIndicator, GlobalFields, Metadata, NetworkOwnerType, Outcome, Page, type ProxyHandler, type ProxyOptions, RawDeviceAttributes, Related, RelatedKind, RelatedType, RelatedUser, RelatedValue, RelatedValues, Relation, RelationInput, RelationRemoval, SIGNALS, SearchEvent, SearchFilters, SearchResult, SharedValue, Signal, SignalDetails, SignalReason, SignalResult, Signals, UnsealOptions, Velocity, Verdict, VerdictAction, VerdictReason, VerifyCheck, VerifyOptions, VerifyResult, VirtualMachineIndicator, Visitor, WebhookEvent, ZenoError, ZenoErrorCode, createClient, createProxy, unsealResult, verifyWebhook };
|
package/dist/server/index.d.ts
CHANGED
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
import { a as ApiOptions, i as ApiKey, n as ProxyOptions, r as createProxy, t as ProxyHandler } from "./proxy-CUZ-Jwgy.js";
|
|
2
2
|
//#region src/server/index.d.ts
|
|
3
3
|
/** Every signal an event checks, the keys of its `signals`. */
|
|
4
|
-
declare const SIGNALS: readonly ['automation', 'headless', 'software-renderer', 'tampering', 'timezone-mismatch', 'privacy-settings', 'vpn', 'proxy', 'tor', 'datacenter', 'abusive-ip', 'incognito', 'virtual-machine', 'developer-tools', 'ai-agent', 'privacy-browser', 'rare-device', 'replayed', 'residential-proxy', 'private-relay', 'forged-payload', 'stored-id-rejected'];
|
|
4
|
+
declare const SIGNALS: readonly ['automation', 'headless', 'software-renderer', 'tampering', 'timezone-mismatch', 'privacy-settings', 'vpn', 'proxy', 'tor', 'datacenter', 'abusive-ip', 'incognito', 'virtual-machine', 'developer-tools', 'ai-agent', 'privacy-browser', 'rare-device', 'high-activity', 'replayed', 'residential-proxy', 'private-relay', 'forged-payload', 'stored-id-rejected'];
|
|
5
5
|
type Signal = (typeof SIGNALS)[number];
|
|
6
6
|
/** The bot verdict: a known good bot (a search engine's crawler), a bad one (automation, a headless browser), or none. */
|
|
7
7
|
type Bot = 'good' | 'bad' | 'not-detected';
|
|
8
8
|
/**
|
|
9
9
|
* Why a signal's `detected` is `null`: what it reads was missing, so it couldn't be checked. The ip lookup failed or
|
|
10
10
|
* took too long; the browser or the connection gave no time zone; a browser probe timed out, failed or wasn't reported;
|
|
11
|
-
* Chromium's static storage quota, the same in normal and private windows; no WebGL or canvas;
|
|
12
|
-
*
|
|
11
|
+
* Chromium's static storage quota, the same in normal and private windows; no WebGL or canvas; too few devices were
|
|
12
|
+
* seen yet to call hardware rare; the request carried no nonce.
|
|
13
13
|
*/
|
|
14
14
|
type SignalReason = 'ip-lookup-failed' | 'ip-lookup-timeout' | 'no-time-zone' | 'no-ip-time-zone' | 'probe-timeout' | 'probe-failed' | 'not-collected' | 'no-webgl' | 'no-canvas' | 'too-few-visitors' | 'no-nonce';
|
|
15
15
|
type Confidence = 'high' | 'medium' | 'low';
|
|
@@ -38,10 +38,109 @@ type Velocity = {
|
|
|
38
38
|
distinctIpByExternalId: number;
|
|
39
39
|
distinctVisitorIdByExternalId: number;
|
|
40
40
|
};
|
|
41
|
+
/**
|
|
42
|
+
* What's global about an event, up to the event: its device and ip across every project using Zeno, as numbers and
|
|
43
|
+
* coarse network facts. Only on getEvent and verify; none when the project turned it off.
|
|
44
|
+
*/
|
|
45
|
+
type GlobalFields = {
|
|
46
|
+
/** The device's history across every project, from its latest 1,000 events. */
|
|
47
|
+
history?: {
|
|
48
|
+
/** The month any project first saw the device, among the events still kept. */
|
|
49
|
+
firstSeenAt?: string;
|
|
50
|
+
events: number;
|
|
51
|
+
/** Its events' risk scores; the event's own `riskScore` is this request's. */
|
|
52
|
+
riskScore: {
|
|
53
|
+
highest: number;
|
|
54
|
+
average: number;
|
|
55
|
+
};
|
|
56
|
+
badBotEvents: number;
|
|
57
|
+
/**
|
|
58
|
+
* The visitor's latest residential connections in your project, up to 10, newest first. Never another
|
|
59
|
+
* project's.
|
|
60
|
+
*/
|
|
61
|
+
residentialIps: EventIp[];
|
|
62
|
+
/**
|
|
63
|
+
* The device's residential networks on every project, up to 10, latest first. Never an address or what locates
|
|
64
|
+
* someone.
|
|
65
|
+
*/
|
|
66
|
+
residentialNetworks: Omit<EventIp, 'address' | 'city' | 'postalCode' | 'latitude' | 'longitude' | 'locationAccuracy' | 'networkRange'>[];
|
|
67
|
+
};
|
|
68
|
+
globalVelocity?: Record<'5m' | '1h' | '24h', Pick<Velocity, 'events' | 'distinctIp' | 'distinctExternalId' | 'distinctCountry'> & {
|
|
69
|
+
/** Every device's events from the event's ip, on every project. */
|
|
70
|
+
ipEvents: number;
|
|
71
|
+
}>;
|
|
72
|
+
};
|
|
73
|
+
/**
|
|
74
|
+
* What the browser reported. Values that could identify a device on their own are hashes of your project's own, so you
|
|
75
|
+
* can compare your events, but they never match another project's; ones many devices share, like the screen, are as
|
|
76
|
+
* reported. Each is left out when the browser didn't report it.
|
|
77
|
+
*/
|
|
78
|
+
type RawDeviceAttributes = {
|
|
79
|
+
canvas?: string;
|
|
80
|
+
canvasText?: string;
|
|
81
|
+
audio?: string;
|
|
82
|
+
webgl?: {
|
|
83
|
+
vendor: string;
|
|
84
|
+
renderer: string;
|
|
85
|
+
extensions: string;
|
|
86
|
+
parameters: string;
|
|
87
|
+
};
|
|
88
|
+
screen?: {
|
|
89
|
+
width: number;
|
|
90
|
+
height: number;
|
|
91
|
+
colorDepth: number;
|
|
92
|
+
pixelRatio: number;
|
|
93
|
+
};
|
|
94
|
+
hardwareConcurrency?: number;
|
|
95
|
+
deviceMemory?: number;
|
|
96
|
+
maxTouchPoints?: number;
|
|
97
|
+
platform?: string;
|
|
98
|
+
architecture?: number;
|
|
99
|
+
vendor?: string;
|
|
100
|
+
oscpu?: string;
|
|
101
|
+
deviceModel?: string;
|
|
102
|
+
timeZone?: string;
|
|
103
|
+
timezoneOffsets?: number[];
|
|
104
|
+
languages?: string[];
|
|
105
|
+
dateTimeLocale?: string;
|
|
106
|
+
cookies?: boolean;
|
|
107
|
+
localStorage?: boolean;
|
|
108
|
+
sessionStorage?: boolean;
|
|
109
|
+
indexedDb?: boolean;
|
|
110
|
+
plugins?: string;
|
|
111
|
+
fonts?: string;
|
|
112
|
+
emoji?: string;
|
|
113
|
+
fontPreferences?: string;
|
|
114
|
+
math?: string;
|
|
115
|
+
keyboard?: string;
|
|
116
|
+
};
|
|
117
|
+
/** What an event turned out to be, as your backend reports it. */
|
|
118
|
+
type Outcome = 'fraud' | 'legitimate';
|
|
119
|
+
/** What kind of bot an event was. */
|
|
120
|
+
type BotType = 'automation' | 'replayed' | 'forged-request' | 'fake-crawler' | 'crawler' | 'ai-agent';
|
|
121
|
+
/** The bot verdict, and what's known of the bot. */
|
|
122
|
+
type EventBot = {
|
|
123
|
+
result: Bot;
|
|
124
|
+
/** Absent when no bot was detected. */
|
|
125
|
+
type?: BotType;
|
|
126
|
+
/** How sure the type is: `low` for an AI agent that only says what it is. */
|
|
127
|
+
confidence?: Confidence;
|
|
128
|
+
/** Who runs it, like `Google`, when it gives a name we know. */
|
|
129
|
+
provider?: string;
|
|
130
|
+
/** The name it goes by, like `Googlebot`, when it gives one. */
|
|
131
|
+
name?: string;
|
|
132
|
+
/** Whether its network confirmed that name: true for a real crawler, false for one pretending. */
|
|
133
|
+
verified?: boolean;
|
|
134
|
+
};
|
|
41
135
|
/** What owns an ip address or runs its network. */
|
|
42
136
|
type NetworkOwnerType = 'isp' | 'hosting' | 'business' | 'education' | 'government' | 'banking';
|
|
43
|
-
/**
|
|
44
|
-
|
|
137
|
+
/**
|
|
138
|
+
* The connection: its ip address and, from the ip lookup, who owns it and where it is. Only the address when the lookup
|
|
139
|
+
* failed.
|
|
140
|
+
*/
|
|
141
|
+
type EventIp = {
|
|
142
|
+
/** The ip address, as the proxy route passed it. Behind a VPN or proxy, the exit's. */
|
|
143
|
+
address: string;
|
|
45
144
|
/** The country's two-letter code, like `US`. */
|
|
46
145
|
country?: string;
|
|
47
146
|
countryName?: string;
|
|
@@ -85,18 +184,32 @@ type IpInfo = {
|
|
|
85
184
|
/** A private or reserved address that no one on the internet has. */
|
|
86
185
|
reservedAddress: boolean;
|
|
87
186
|
};
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
187
|
+
/** The browser, parsed on the server from the user agent and client hints. */
|
|
188
|
+
type EventBrowser = {
|
|
189
|
+
name: string;
|
|
190
|
+
/** The major version, like `157`. */
|
|
191
|
+
version?: string;
|
|
192
|
+
fullVersion?: string;
|
|
92
193
|
os: string;
|
|
93
194
|
osVersion?: string;
|
|
94
195
|
device: string;
|
|
196
|
+
/** The browser's user agent string, as it sent it. */
|
|
197
|
+
userAgent: string;
|
|
95
198
|
};
|
|
96
199
|
/** What some signals found, on their entry in `signals` when they're detected, each field only when there was one. */
|
|
97
200
|
type SignalDetails = {
|
|
98
201
|
vpn: {
|
|
99
202
|
confidence?: Confidence;
|
|
203
|
+
/** Why it's a VPN: a known exit, iCloud Private Relay or a time zone that doesn't fit. */
|
|
204
|
+
methods?: {
|
|
205
|
+
knownVpnExit: boolean;
|
|
206
|
+
privateRelay: boolean;
|
|
207
|
+
timeZoneMismatch: boolean;
|
|
208
|
+
};
|
|
209
|
+
/** The browser's own time zone, likely where the person really is. */
|
|
210
|
+
originTimeZone?: string;
|
|
211
|
+
/** The country of that time zone, like `DE`: a hint, not proof. */
|
|
212
|
+
originCountry?: string;
|
|
100
213
|
};
|
|
101
214
|
proxy: {
|
|
102
215
|
confidence?: Confidence;
|
|
@@ -164,7 +277,7 @@ type Event = {
|
|
|
164
277
|
verdict: Verdict;
|
|
165
278
|
/** 0 to 30: the detected signals' points, capped at 30. */
|
|
166
279
|
riskScore: number;
|
|
167
|
-
bot:
|
|
280
|
+
bot: EventBot;
|
|
168
281
|
/** How sure the visitor id is, 0.1 to 1. */
|
|
169
282
|
confidence: number;
|
|
170
283
|
/**
|
|
@@ -180,28 +293,40 @@ type Event = {
|
|
|
180
293
|
/** The id of the API key whose proxy route identified (search filters on it as `apiKeyId`). */
|
|
181
294
|
apiKeyId: string;
|
|
182
295
|
createdAt: string;
|
|
183
|
-
/**
|
|
296
|
+
/**
|
|
297
|
+
* When `verify` attached its external id or an outcome was reported afterwards; that also sends an `update`
|
|
298
|
+
* webhook.
|
|
299
|
+
*/
|
|
184
300
|
updatedAt?: string;
|
|
185
|
-
/** When the project's retention removes it (ISO), 3 years after the event at most. Not in search results. */
|
|
186
|
-
expiresAt?: string;
|
|
187
301
|
origin?: string;
|
|
188
302
|
/** The page as origin and path, or only its origin; left out when the project keeps no page urls (`pageUrls`). */
|
|
189
303
|
url?: string;
|
|
190
304
|
referrer?: string;
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
browserDetails: BrowserDetails;
|
|
194
|
-
ip: string;
|
|
195
|
-
/** Who owns the ip and where it is, with its `country` and `timeZone`; none when the lookup failed. */
|
|
196
|
-
ipInfo?: IpInfo;
|
|
305
|
+
browser: EventBrowser;
|
|
306
|
+
ip: EventIp;
|
|
197
307
|
/**
|
|
198
308
|
* Every signal Zeno checks: `detected` true, false, or null when it couldn't be checked (with a `reason`), the
|
|
199
309
|
* `points` a detected one added, and what it found. Read `event.signals.vpn.detected`.
|
|
200
310
|
*/
|
|
201
311
|
signals: Signals;
|
|
312
|
+
/** What your backend reported the event turned out to be (`reportOutcome`). */
|
|
313
|
+
outcome?: Outcome;
|
|
314
|
+
/** A looser id than `visitorId`: the hardware alone, shared by identical devices. Only on getEvent and verify. */
|
|
315
|
+
broadVisitorId?: string;
|
|
316
|
+
/**
|
|
317
|
+
* The approximate area, as an id per project, with a radius in km. None behind a VPN or proxy. Only on getEvent and
|
|
318
|
+
* verify.
|
|
319
|
+
*/
|
|
320
|
+
proximity?: {
|
|
321
|
+
id: string;
|
|
322
|
+
radius: number;
|
|
323
|
+
confidence: number;
|
|
324
|
+
};
|
|
325
|
+
/** Only on getEvent and verify, not in webhooks or sealed results. */
|
|
326
|
+
rawDeviceAttributes?: RawDeviceAttributes;
|
|
202
327
|
/** Only on getEvent and verify, not in webhooks or sealed results. */
|
|
203
328
|
velocity?: Record<'5m' | '1h' | '24h', Velocity>;
|
|
204
|
-
};
|
|
329
|
+
} & GlobalFields;
|
|
205
330
|
/** A list filter takes one value, or several to match any of. */
|
|
206
331
|
type AnyOf<T> = T | T[];
|
|
207
332
|
type SearchFilters = {
|
|
@@ -219,6 +344,8 @@ type SearchFilters = {
|
|
|
219
344
|
action?: AnyOf<string>;
|
|
220
345
|
signal?: AnyOf<Signal>;
|
|
221
346
|
bot?: AnyOf<Bot>;
|
|
347
|
+
/** What your backend reported, among the events with a report. */
|
|
348
|
+
outcome?: AnyOf<Outcome>;
|
|
222
349
|
minRiskScore?: number;
|
|
223
350
|
/**
|
|
224
351
|
* Inclusive. Without it the search covers the 30 days before `end` (or now), unless it looks up a `visitorId`,
|
|
@@ -232,16 +359,17 @@ type SearchFilters = {
|
|
|
232
359
|
};
|
|
233
360
|
/**
|
|
234
361
|
* An event as the search lists it: a subset of the event's own fields, with the same names. It leaves out `returning`,
|
|
235
|
-
* `metadata`, `updatedAt`, `
|
|
236
|
-
*
|
|
237
|
-
* version, and its `
|
|
362
|
+
* `metadata`, `updatedAt`, `url`, `referrer` and `velocity`; its `signals` list only the detected ones, as `{ detected:
|
|
363
|
+
* true }` (get the event for the rest), its `browser` holds the user agent, and the browser's and the os's name and
|
|
364
|
+
* version, and its `ip` the address with the country, city, asn and company, each left out when the event has none of
|
|
365
|
+
* them.
|
|
238
366
|
*/
|
|
239
|
-
type SearchEvent = Pick<Event, 'requestId' | 'visitorId' | 'verdict' | 'riskScore' | 'bot' | 'confidence' | 'externalId' | 'action' | 'apiKeyId' | 'createdAt' | 'origin'
|
|
367
|
+
type SearchEvent = Pick<Event, 'requestId' | 'visitorId' | 'verdict' | 'riskScore' | 'bot' | 'outcome' | 'confidence' | 'externalId' | 'action' | 'apiKeyId' | 'createdAt' | 'origin'> & {
|
|
240
368
|
signals: { [S in Signal]?: {
|
|
241
369
|
detected: true;
|
|
242
370
|
}; };
|
|
243
|
-
|
|
244
|
-
|
|
371
|
+
browser: Pick<EventBrowser, 'userAgent'> & Partial<Pick<EventBrowser, 'name' | 'version' | 'os' | 'osVersion'>>;
|
|
372
|
+
ip: Pick<EventIp, 'address' | 'country' | 'city' | 'asn' | 'company'>;
|
|
245
373
|
};
|
|
246
374
|
/** A page of a list: pass `cursor` back for the next one; none on the last. */
|
|
247
375
|
type Page<T> = {
|
|
@@ -258,7 +386,7 @@ type SearchResult = Page<SearchEvent> & {
|
|
|
258
386
|
/**
|
|
259
387
|
* A visitor: `externalIds` the latest 10 external ids seen with it, newest first, and `externalIdCount` how many there
|
|
260
388
|
* are in all; `signals` holds every signal any of its events detected, as `{ detected: true }`, and `recentEvents` its
|
|
261
|
-
* 20 latest events, newest first, each with its detected signals the same way and `
|
|
389
|
+
* 20 latest events, newest first, each with its detected signals the same way and `ip.country` when known.
|
|
262
390
|
*/
|
|
263
391
|
type Visitor = {
|
|
264
392
|
visitorId: string;
|
|
@@ -270,8 +398,8 @@ type Visitor = {
|
|
|
270
398
|
eventCount: number;
|
|
271
399
|
firstSeenAt: string;
|
|
272
400
|
lastSeenAt: string;
|
|
273
|
-
recentEvents: (Pick<SearchEvent, 'requestId' | 'externalId' | 'createdAt' | '
|
|
274
|
-
|
|
401
|
+
recentEvents: (Pick<SearchEvent, 'requestId' | 'externalId' | 'createdAt' | 'signals'> & {
|
|
402
|
+
ip: Pick<EventIp, 'address' | 'country'>;
|
|
275
403
|
})[];
|
|
276
404
|
};
|
|
277
405
|
/**
|
|
@@ -350,7 +478,10 @@ type RelatedUser = {
|
|
|
350
478
|
externalId: string;
|
|
351
479
|
createdAt: string;
|
|
352
480
|
};
|
|
353
|
-
/**
|
|
481
|
+
/**
|
|
482
|
+
* A value more than one user shares, or for a relation type the two users it ties; `count` is how many users share it
|
|
483
|
+
* (2 for a relation).
|
|
484
|
+
*/
|
|
354
485
|
type SharedValue = {
|
|
355
486
|
type: RelatedType;
|
|
356
487
|
weight: number;
|
|
@@ -505,7 +636,14 @@ declare const createClient: (apiKey: ApiKey, options?: ClientOptions) => {
|
|
|
505
636
|
searchEvents: (filters?: SearchFilters) => Promise<SearchResult>;
|
|
506
637
|
/** A visitor (a browser) with every external id seen with it. */
|
|
507
638
|
getVisitor: (visitorId: string) => Promise<Visitor>;
|
|
508
|
-
/**
|
|
639
|
+
/**
|
|
640
|
+
* Reports what an event turned out to be, like after a chargeback or a review. The latest report counts, and it
|
|
641
|
+
* never changes the event's score.
|
|
642
|
+
*/
|
|
643
|
+
reportOutcome: (requestId: string, outcome: Outcome) => Promise<{
|
|
644
|
+
requestId: string;
|
|
645
|
+
outcome: Outcome;
|
|
646
|
+
}>;
|
|
509
647
|
deleteVisitor: (visitorId: string) => Promise<{
|
|
510
648
|
visitorId: string;
|
|
511
649
|
deletedEvents: number;
|
|
@@ -576,7 +714,7 @@ declare const createClient: (apiKey: ApiKey, options?: ClientOptions) => {
|
|
|
576
714
|
/** The client `createClient` makes. */
|
|
577
715
|
type Client = ReturnType<typeof createClient>;
|
|
578
716
|
/** A webhook delivery's body: the event, without its velocity. */
|
|
579
|
-
type WebhookEvent = Omit<Event, 'velocity'>;
|
|
717
|
+
type WebhookEvent = Omit<Event, 'broadVisitorId' | 'proximity' | 'rawDeviceAttributes' | 'velocity' | keyof GlobalFields>;
|
|
580
718
|
/**
|
|
581
719
|
* Checks a webhook delivery's Zeno-Signature header against the project's webhook secret, and that it was signed in the
|
|
582
720
|
* last `tolerance` seconds, so a captured delivery can't be replayed later. Pass the raw body. Resolves to the event
|
|
@@ -615,4 +753,4 @@ type UnsealOptions = {
|
|
|
615
753
|
*/
|
|
616
754
|
declare const unsealResult: (sealed: string | undefined | null, options: UnsealOptions) => Promise<VerifyResult>;
|
|
617
755
|
//#endregion
|
|
618
|
-
export { AddedRelation, type ApiOptions, Bot,
|
|
756
|
+
export { AddedRelation, type ApiOptions, Bot, BotType, Client, ClientOptions, Confidence, Connection, Contradiction, Embed, Event, EventBot, EventBrowser, EventIp, ForgedPayloadIndicator, GlobalFields, Metadata, NetworkOwnerType, Outcome, Page, type ProxyHandler, type ProxyOptions, RawDeviceAttributes, Related, RelatedKind, RelatedType, RelatedUser, RelatedValue, RelatedValues, Relation, RelationInput, RelationRemoval, SIGNALS, SearchEvent, SearchFilters, SearchResult, SharedValue, Signal, SignalDetails, SignalReason, SignalResult, Signals, UnsealOptions, Velocity, Verdict, VerdictAction, VerdictReason, VerifyCheck, VerifyOptions, VerifyResult, VirtualMachineIndicator, Visitor, WebhookEvent, ZenoError, ZenoErrorCode, createClient, createProxy, unsealResult, verifyWebhook };
|
package/dist/server/index.js
CHANGED
|
@@ -42,6 +42,21 @@ const isIpMismatch = (eventIp, ip) => {
|
|
|
42
42
|
const requestIp = ip.trim();
|
|
43
43
|
return eventIp.includes(":") === requestIp.includes(":") && networkOf(eventIp) !== networkOf(requestIp);
|
|
44
44
|
};
|
|
45
|
+
const isNestedDeeperThan = (text, max) => {
|
|
46
|
+
let depth = 0;
|
|
47
|
+
let isInString = false;
|
|
48
|
+
for (let index = 0; index < text.length; index++) {
|
|
49
|
+
const char = text[index];
|
|
50
|
+
if (isInString) {
|
|
51
|
+
if (char === "\\") index++;
|
|
52
|
+
else if (char === "\"") isInString = false;
|
|
53
|
+
} else if (char === "\"") isInString = true;
|
|
54
|
+
else if (char === "{" || char === "[") {
|
|
55
|
+
if (++depth > max) return true;
|
|
56
|
+
} else if (char === "}" || char === "]") depth--;
|
|
57
|
+
}
|
|
58
|
+
return false;
|
|
59
|
+
};
|
|
45
60
|
//#endregion
|
|
46
61
|
//#region src/server/proxy.ts
|
|
47
62
|
const isStrings = (value) => {
|
|
@@ -53,6 +68,7 @@ const rawHeadersOf = (internal) => {
|
|
|
53
68
|
};
|
|
54
69
|
const COOKIE = "zeno_id";
|
|
55
70
|
const MAX_BODY = 131072;
|
|
71
|
+
const MAX_NESTING = 64;
|
|
56
72
|
const TIMEOUT$1 = 1e4;
|
|
57
73
|
const jsonResponse = (status, body, headers = {}) => {
|
|
58
74
|
return new Response(JSON.stringify(body), {
|
|
@@ -283,9 +299,10 @@ const createProxy = (apiKey, options = {}) => {
|
|
|
283
299
|
};
|
|
284
300
|
const handlePost = async (request, ip, internal) => {
|
|
285
301
|
if (!/^application\/json\s*(;|$)/i.test(request.headers.get("content-type") ?? "")) return invalidRequest("The body must be JSON");
|
|
286
|
-
if (request.headers.get("sec-fetch-site") === "cross-site") return invalidRequest("Cross-site requests are refused");
|
|
302
|
+
if (request.headers.get("sec-fetch-site")?.toLowerCase() === "cross-site") return invalidRequest("Cross-site requests are refused");
|
|
287
303
|
const bodyText = await readCappedBody(request, MAX_BODY);
|
|
288
304
|
if (bodyText === void 0) return invalidRequest("The body is larger than 128 KB");
|
|
305
|
+
if (isNestedDeeperThan(bodyText, MAX_NESTING)) return invalidRequest(`The body nests deeper than ${MAX_NESTING} levels`);
|
|
289
306
|
let payload;
|
|
290
307
|
try {
|
|
291
308
|
payload = JSON.parse(bodyText);
|
|
@@ -379,6 +396,7 @@ const SIGNALS = [
|
|
|
379
396
|
"ai-agent",
|
|
380
397
|
"privacy-browser",
|
|
381
398
|
"rare-device",
|
|
399
|
+
"high-activity",
|
|
382
400
|
"replayed",
|
|
383
401
|
"residential-proxy",
|
|
384
402
|
"private-relay",
|
|
@@ -430,7 +448,7 @@ const defineShape = (name, fields) => ({
|
|
|
430
448
|
const EVENT = defineShape("an event", {
|
|
431
449
|
requestId: "string",
|
|
432
450
|
visitorId: "string",
|
|
433
|
-
ip: "
|
|
451
|
+
ip: "object",
|
|
434
452
|
createdAt: "string",
|
|
435
453
|
riskScore: "number",
|
|
436
454
|
signals: "object",
|
|
@@ -443,6 +461,10 @@ const VISITOR = defineShape("a visitor", {
|
|
|
443
461
|
externalIdCount: "number",
|
|
444
462
|
recentEvents: "array"
|
|
445
463
|
});
|
|
464
|
+
const REPORTED_OUTCOME = defineShape("a reported outcome", {
|
|
465
|
+
requestId: "string",
|
|
466
|
+
outcome: "string"
|
|
467
|
+
});
|
|
446
468
|
const DELETED_VISITOR = defineShape("an erasure", {
|
|
447
469
|
visitorId: "string",
|
|
448
470
|
deletedEvents: "number"
|
|
@@ -581,7 +603,16 @@ const createClient = (apiKey, options = {}) => {
|
|
|
581
603
|
},
|
|
582
604
|
/** A visitor (a browser) with every external id seen with it. */
|
|
583
605
|
getVisitor: async (visitorId) => callApi("GET", `/visitors/${toPathSegment("visitorId", visitorId)}`, VISITOR),
|
|
584
|
-
/**
|
|
606
|
+
/**
|
|
607
|
+
* Reports what an event turned out to be, like after a chargeback or a review. The latest report counts, and it
|
|
608
|
+
* never changes the event's score.
|
|
609
|
+
*/
|
|
610
|
+
reportOutcome: (requestId, outcome) => {
|
|
611
|
+
return callApi("POST", "/outcomes", REPORTED_OUTCOME, {
|
|
612
|
+
requestId,
|
|
613
|
+
outcome
|
|
614
|
+
});
|
|
615
|
+
},
|
|
585
616
|
deleteVisitor: async (visitorId) => {
|
|
586
617
|
return callApi("DELETE", `/visitors/${toPathSegment("visitorId", visitorId)}`, DELETED_VISITOR);
|
|
587
618
|
},
|
|
@@ -717,8 +748,8 @@ const MISSING_KEY = "unsealResult needs the project's encryption key as key (is
|
|
|
717
748
|
const keyBytesOf = (secret) => {
|
|
718
749
|
const trimmedKey = requireSecret(secret, MISSING_KEY).trim();
|
|
719
750
|
const keyBytes = /^[A-Za-z0-9+/]+={0,2}$/.test(trimmedKey) ? fromBase64(trimmedKey) : void 0;
|
|
720
|
-
if (!keyBytes) throw new TypeError("unsealResult's key isn't base64: pass the project's encryption key as the
|
|
721
|
-
if (keyBytes.length !== 32) throw new TypeError(/^[0-9a-f]{64}$/i.test(trimmedKey) ? "unsealResult's key looks like hex: pass the project's encryption key as the
|
|
751
|
+
if (!keyBytes) throw new TypeError("unsealResult's key isn't base64: pass the project's encryption key as the app shows it");
|
|
752
|
+
if (keyBytes.length !== 32) throw new TypeError(/^[0-9a-f]{64}$/i.test(trimmedKey) ? "unsealResult's key looks like hex: pass the project's encryption key as the app shows it, in base64" : `unsealResult's key is ${keyBytes.length} bytes, not 32: pass the project's encryption key as the app shows it`);
|
|
722
753
|
return keyBytes;
|
|
723
754
|
};
|
|
724
755
|
const decryptWithAnyKey = async (keys, data) => {
|
|
@@ -763,7 +794,7 @@ const unsealResult = async (sealed, options) => {
|
|
|
763
794
|
if (!EVENT.is(event)) throw new Error("The sealed result opened but isn't an event; update zeno.id/server");
|
|
764
795
|
const failedChecks = [];
|
|
765
796
|
const maxAge = options.maxAge ?? UNSEAL_MAX_AGE;
|
|
766
|
-
if (options.ip && isIpMismatch(event.ip, options.ip)) failedChecks.push("ip-mismatch");
|
|
797
|
+
if (options.ip && isIpMismatch(event.ip.address, options.ip)) failedChecks.push("ip-mismatch");
|
|
767
798
|
if (Date.now() - Date.parse(event.createdAt) > maxAge * 1e3) failedChecks.push("too-old");
|
|
768
799
|
if (options.externalId !== void 0 && event.externalId !== void 0 && event.externalId !== options.externalId) failedChecks.push("external-id-mismatch");
|
|
769
800
|
if (failedChecks.length > 0) return {
|