zeno.id 0.3.0 → 0.3.2
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 +29 -10
- package/dist/server/index.cjs +18 -1
- package/dist/server/index.js +18 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -18,21 +18,24 @@ One package for the browser and the server. `zeno.id/server` holds your API key,
|
|
|
18
18
|
ZENO_API_KEY=sk_...
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
-
2. Make the proxy route
|
|
21
|
+
2. Make the proxy route once, with the key, and mount it on your site at a path of your choice (`/zeno` here).
|
|
22
22
|
3. In the browser, on a page with an action you want to identify (a login, signup or checkout), `start()` the browser SDK (`zeno.id`) with the same path when the page loads (it gathers signals; nothing is sent or billed), call `identify()` when the user takes the action, the identity check, and send its `requestId` to your server with the action's request.
|
|
23
|
-
4. On your server, `verify` the request ID and allow, challenge or block.
|
|
23
|
+
4. On your server, make an API client with the same key, `verify` the request ID and allow, challenge or block.
|
|
24
24
|
|
|
25
25
|
```ts
|
|
26
26
|
// zeno.ts
|
|
27
|
-
import {
|
|
27
|
+
import { createProxy } from 'zeno.id/server'
|
|
28
28
|
|
|
29
29
|
// Your proxy route: the browser SDK talks to Zeno through it
|
|
30
30
|
export const zeno = createProxy(process.env.ZENO_API_KEY)
|
|
31
|
-
// For verify() in your server's handlers
|
|
32
|
-
export const client = createClient(process.env.ZENO_API_KEY)
|
|
33
31
|
```
|
|
34
32
|
|
|
35
33
|
```ts
|
|
34
|
+
import { createClient } from 'zeno.id/server'
|
|
35
|
+
|
|
36
|
+
// Your API client, made once with the project's API key
|
|
37
|
+
const client = createClient(process.env.ZENO_API_KEY)
|
|
38
|
+
|
|
36
39
|
// After the password matched:
|
|
37
40
|
const {
|
|
38
41
|
action, // 'allow', 'challenge' or 'block'
|
|
@@ -229,7 +232,9 @@ app.all('/zeno', nodeHandler(zeno)) // the path you chose
|
|
|
229
232
|
import { zeno } from '@/lib/zeno'
|
|
230
233
|
|
|
231
234
|
// X-Real-IP: set by Vercel, or by your own proxy (nginx: proxy_set_header X-Real-IP $remote_addr;)
|
|
232
|
-
const handler = (request: Request) =>
|
|
235
|
+
const handler = (request: Request) => {
|
|
236
|
+
return zeno(request, request.headers.get('x-real-ip'))
|
|
237
|
+
}
|
|
233
238
|
|
|
234
239
|
// Next.js calls the export named after the method
|
|
235
240
|
export const GET = handler
|
|
@@ -277,7 +282,7 @@ The route checks a `POST` before it calls Zeno: a JSON body of at most 128 KB wi
|
|
|
277
282
|
|
|
278
283
|
## Verify
|
|
279
284
|
|
|
280
|
-
`client.verify(requestId, { ip?, externalId?, maxAge? }?)` sends the request ID to `POST /verify`, which checks it and answers `{ action, reasons, event? }`. Each request ID verifies once. The event comes with its `velocity`, as `getEvent` has it, from before verify attached your `externalId`: `event.velocity['24h'].distinctExternalId` counts the users seen on this browser today, and `sameAction` its events with this event's action, for a site without external IDs. Identical devices can look like one browser, so treat a busy one as a lead to review.
|
|
285
|
+
`client.verify(requestId, { ip?, externalId?, maxAge?, idempotencyKey? }?)` sends the request ID to `POST /verify`, which checks it and answers `{ action, reasons, event? }`. Each request ID verifies once. The event comes with its `velocity`, as `getEvent` has it, from before verify attached your `externalId`: `event.velocity['24h'].distinctExternalId` counts the users seen on this browser today, and `sameAction` its events with this event's action, for a site without external IDs. Identical devices can look like one browser, so treat a busy one as a lead to review.
|
|
281
286
|
|
|
282
287
|
| Answer | When |
|
|
283
288
|
| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -302,10 +307,24 @@ const { action } = await client.verify(requestId, {
|
|
|
302
307
|
|
|
303
308
|
`ip` is optional: pass the same client IP your proxy route got, not your load balancer's, and a request ID sent from another ip blocks with `ip-mismatch`; leave it out (or pass `null` or `undefined`) and there's no ip check, as there's none between an IPv4 and an IPv6 address. `no-request-id` is a `challenge` so you decide: ask for a second factor, or let it through and flag the account; never treat it as verified. API errors throw a `ZenoError`.
|
|
304
309
|
|
|
310
|
+
A lost answer is safe to retry. Each call sends an `idempotencyKey`, and after a network error or a `5xx` the SDK sends it again, twice at most, with the same key; a repeat with the same key within 5 minutes answers what the first call did instead of `already-used`. If your own code may send the same verify again (a retried job, a second try of your handler), pass your own `idempotencyKey`, 8 to 128 characters, like your request's ID.
|
|
311
|
+
|
|
312
|
+
### Test keys
|
|
313
|
+
|
|
314
|
+
For automated tests and staging, use a test key in place of your API key, in `createProxy` and `createClient`. Each answers `verify` the same every time, with a sample event; nothing is stored or billed, a test request ID can be verified again and again, and other calls refuse a test key. Without a request ID each answers `challenge` with `no-request-id`, like a real key.
|
|
315
|
+
|
|
316
|
+
| Test key | `verify` answers |
|
|
317
|
+
| ------------------- | ----------------------- |
|
|
318
|
+
| `sk_test_allow` | `allow` |
|
|
319
|
+
| `sk_test_challenge` | `challenge`, with `vpn` |
|
|
320
|
+
| `sk_test_block` | `block`, with `bad-bot` |
|
|
321
|
+
|
|
305
322
|
## Server API
|
|
306
323
|
|
|
307
324
|
```ts
|
|
308
|
-
import {
|
|
325
|
+
import { createClient } from 'zeno.id/server'
|
|
326
|
+
|
|
327
|
+
const client = createClient(process.env.ZENO_API_KEY)
|
|
309
328
|
|
|
310
329
|
const event = await client.getEvent(requestId)
|
|
311
330
|
const { items, cursor } = await client.searchEvents({
|
|
@@ -344,7 +363,7 @@ const { url } = await client.createEmbed({
|
|
|
344
363
|
|
|
345
364
|
| Method | Call |
|
|
346
365
|
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
347
|
-
| `verify(requestId, { ip?, externalId?, maxAge? }?)`
|
|
366
|
+
| `verify(requestId, { ip?, externalId?, maxAge?, idempotencyKey? }?)` | `POST /verify` |
|
|
348
367
|
| `getEvent(requestId)` | `GET /events/{requestId}` |
|
|
349
368
|
| `searchEvents(filters)` | `GET /events?...` |
|
|
350
369
|
| `getVisitor(visitorId)` | `GET /visitors/{visitorId}` |
|
|
@@ -362,7 +381,7 @@ A list filter (`apiKeyId`, `country`, `origin`, `asn`, `browser`, `os`, `action`
|
|
|
362
381
|
|
|
363
382
|
A failed call throws a `ZenoError` with the `status` and the API's error `code` (`ZenoErrorCode`), like `not_found`. A call answered `429 rate_limited` or `503 search_unavailable` is sent again after the API's `Retry-After`, twice, a little later each time at random so calls limited together don't all come back at once; the error of one that stays limited has `retryAfter` in seconds. Neither was carried out, so retrying a write or a delete is safe.
|
|
364
383
|
|
|
365
|
-
The SDK's own codes: `network_error` (status `0`) when the API can't be reached or doesn't answer within 10 seconds,
|
|
384
|
+
The SDK's own codes: `network_error` (status `0`) when the API can't be reached or doesn't answer within 10 seconds, retried only for `verify` (above); `invalid_request` with status `0` for an empty id (`getEvent('')`), refused before anything is sent; `request_failed` for an error answer without a code, or a success answer that isn't what the call returns (each answer is checked before it's handed back, so something between your server and Zeno that answers otherwise fails here rather than later in your code).
|
|
366
385
|
|
|
367
386
|
`addRelation` is the one billed call: each is billed like an identification and counts toward the free monthly identifications and the spend limits (reads, `createEmbed` and what events relate by themselves are free). Once a spend limit you set for the project, its organization or the key is reached it throws a `402` `spend_limit_reached` and adds nothing. Every call answers `402` `account_closed` while Zeno has closed the organization's account (for unpaid invoices); contact support to reopen it.
|
|
368
387
|
|
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);
|
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);
|