zeno.id 0.0.0-stage → 0.2.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/LICENSE +21 -0
- package/README.md +404 -2
- package/dist/index.cjs +233 -0
- package/dist/index.d.cts +87 -0
- package/dist/index.d.ts +87 -0
- package/dist/index.js +230 -0
- package/dist/server/index.cjs +773 -0
- package/dist/server/index.d.cts +606 -0
- package/dist/server/index.d.ts +606 -0
- package/dist/server/index.js +767 -0
- package/dist/server/node.cjs +88 -0
- package/dist/server/node.d.cts +21 -0
- package/dist/server/node.d.ts +21 -0
- package/dist/server/node.js +87 -0
- package/dist/server/proxy-CUZ-Jwgy.d.cts +36 -0
- package/dist/server/proxy-CUZ-Jwgy.d.ts +36 -0
- package/package.json +69 -5
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Creative Code Solutions B.V.
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,405 @@
|
|
|
1
|
-
#
|
|
1
|
+
# zeno.id
|
|
2
2
|
|
|
3
|
-
This
|
|
3
|
+
Zeno tells your server whether a login, signup or checkout came from a real browser, and whether to let it through. This package has both sides. In the browser, `zeno.id` is a small loader: `start()` imports the script itself at runtime through a route on your own site (the proxy route), so collection fixes reach every site without a release, and `identify()` answers a request ID for your server to verify. On your server, `zeno.id/server` is that proxy route, which adds your API key and passes the script's signals on to Zeno, a typed client for the Zeno API with `verify`, and the helpers for webhooks and sealed results.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
npm install zeno.id
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
One package for the browser and the server. `zeno.id/server` holds your API key, so import it on your server only. It uses only standard web APIs, so it runs on Node 20+, Bun, Deno, Cloudflare Workers, Vercel and Netlify edge, with no compatibility flags; `zeno.id/server/node` adds `nodeHandler` for Express, Fastify and Node's http server. A browser bundle of `zeno.id` holds the loader only, none of the server code. Every entry ships ES modules, CommonJS and their types. Not JavaScript? The Zeno API is plain HTTP: the docs' server API reference has every call.
|
|
12
|
+
|
|
13
|
+
## How it fits together
|
|
14
|
+
|
|
15
|
+
1. Make a project and an API key in the dashboard, and put the key in your server's environment:
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
ZENO_API_KEY=sk_...
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
2. Make the proxy route and the API client once, with the key, and mount the route on your site at a path of your choice (`/zeno` here).
|
|
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.
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
// zeno.ts
|
|
27
|
+
import { createClient, createProxy } from 'zeno.id/server'
|
|
28
|
+
|
|
29
|
+
// Your proxy route: the browser SDK talks to Zeno through it
|
|
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
|
+
```
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
// After the password matched:
|
|
37
|
+
const {
|
|
38
|
+
action, // 'allow', 'challenge' or 'block'
|
|
39
|
+
reasons, // why, like ['vpn', 'automation']
|
|
40
|
+
event, // the full event (visitor ID, IP, signals, velocity…), when found
|
|
41
|
+
} = await client.verify(requestId)
|
|
42
|
+
|
|
43
|
+
if (action === 'block') {
|
|
44
|
+
// Refuse, or hold it for review
|
|
45
|
+
} else if (action === 'challenge') {
|
|
46
|
+
// Ask for a second factor
|
|
47
|
+
}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
The package reads no option or secret from the environment: `createProxy(apiKey, options?)` and `createClient(apiKey, options?)` take the key from `process.env` or wherever your secrets live (`env` on Cloudflare Workers). It may be `undefined` where the route or client is made: neither fails at import or at build time, where the environment may be missing (Next.js collecting page data), and a call, or a request to the route, without it fails saying how to set it. Both know where the Zeno API is; `apiUrl` in their options is only for another Zeno API than the live one.
|
|
51
|
+
|
|
52
|
+
## In the browser
|
|
53
|
+
|
|
54
|
+
Call `start()` on a page with an action you want to identify (a login, signup or checkout), when that page loads, not on every page, with the path of your route on your site. It loads Zeno's script and starts gathering signals in the browser; nothing is sent to Zeno and nothing is billed. Call `identify()` when the user takes the action: that's the identity check, it sends the report and gives you the request ID. Starting early only makes `identify()` quick, and one `start()` serves every `identify()` on that page. Call it in a module, not in a component (a component remounts, and each `start()` collects again). A module's top level is fine in any framework: while a page renders on the server, `start()` does nothing and its `identify()` answers the `not_in_browser` error.
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
import { start } from 'zeno.id'
|
|
58
|
+
|
|
59
|
+
// When the login page loads:
|
|
60
|
+
const zeno = start('/zeno') // the same path as your route
|
|
61
|
+
|
|
62
|
+
// When the user logs in (never throws; requestId is undefined when it failed):
|
|
63
|
+
const { requestId } = await zeno.identify({ action: 'login' })
|
|
64
|
+
|
|
65
|
+
const response = await fetch('/api/login', {
|
|
66
|
+
method: 'POST',
|
|
67
|
+
headers: { 'Content-Type': 'application/json' },
|
|
68
|
+
body: JSON.stringify({
|
|
69
|
+
email,
|
|
70
|
+
password,
|
|
71
|
+
requestId,
|
|
72
|
+
}),
|
|
73
|
+
})
|
|
74
|
+
|
|
75
|
+
if (response.ok) {
|
|
76
|
+
location.assign('/account')
|
|
77
|
+
} else {
|
|
78
|
+
// A wrong password, or a block or challenge from your server
|
|
79
|
+
showError(await response.text())
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Your server then calls `client.verify(requestId)` from `zeno.id/server`, which answers `allow`, `challenge` or `block`: that's the answer to trust, never anything the browser says. A login request without a request ID gets `challenge` with `no-request-id`, so your server decides whether to let the action through or ask for more; a request ID verifies once. A project in zero trust mode answers only `requestId` (no `visitorId` or `returning`), and one with sealed results also returns `sealedResult` for your server to open with `unsealResult`.
|
|
84
|
+
|
|
85
|
+
`start()` imports the script as an ES module from that path, and the script identifies with a `POST` to the same path. Nothing else is tried: on a failure `identify()` resolves at once with its error (`script_load_failed`, `csp_block`, `network_connection`…).
|
|
86
|
+
|
|
87
|
+
The script also sends the page url and referrer as origin and path only, without the query string or `#fragment`; set `pageUrls` in the project's settings to `origin` to keep only the site, or `none` to keep neither.
|
|
88
|
+
|
|
89
|
+
### Content Security Policy
|
|
90
|
+
|
|
91
|
+
- `script-src 'self'` for the script's code from the route, and `connect-src 'self'` for the identification and `forget()`.
|
|
92
|
+
- `script-src blob:` and `worker-src blob:` for some of the script's checks (no `eval`). Without them those checks go unreported and the identification still works.
|
|
93
|
+
|
|
94
|
+
```
|
|
95
|
+
Content-Security-Policy: script-src 'self' blob:; connect-src 'self'; worker-src 'self' blob:
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
The script's code uses no `eval` or `new Function`, so `'unsafe-eval'` isn't needed.
|
|
99
|
+
|
|
100
|
+
### Options
|
|
101
|
+
|
|
102
|
+
`start(path)` takes your proxy route's path on this site, `/zeno` when you leave it out. It starts with `/`; a full url, a query string or a `#fragment` is refused with `invalid_options`, since the route answers the page's own origin only.
|
|
103
|
+
|
|
104
|
+
| `identify()` option | |
|
|
105
|
+
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
106
|
+
| `externalId` | Your id for the user behind the browser, to look visitors up by and to delete later. 1 to 256 characters (`invalid_options` otherwise). |
|
|
107
|
+
| `action` | What the visitor is doing, like `login`, `signup` or `checkout`, up to 1,024 characters. Returned with the event. |
|
|
108
|
+
| `metadata` | Your own key-values kept with the event, like `{ orderId: 'A-1042', plan: 'pro' }`: up to 20 keys of 1 to 40 letters, digits, `_`, `.` or `-`, each a string up to 256 characters, a number or a boolean, 2 KB in all. Returned with the event, never used for detection. |
|
|
109
|
+
|
|
110
|
+
The script keeps no visitor id itself. The route keeps it in the `zeno_id` cookie (`HttpOnly`, `SameSite=Lax`, `Secure` on https, a year), on the route's own path, so two routes on one site, like a site's own login and a demo, keep separate ids. Zeno reuses it while it's still the same device, so the id survives browser updates. The script keeps nothing in the browser's storage, and every `identify()` identifies again.
|
|
111
|
+
|
|
112
|
+
### Stop and forget
|
|
113
|
+
|
|
114
|
+
`zeno.stop()` ends identification for good, for a visitor who withdraws consent: an `identify()` in progress and every later one answer the `stopped` error, nothing more is collected or sent, and a `POST` to the route's `?forget` clears its cookie. A script still loading never starts: its module may finish downloading, but it isn't started. `forget(path)` does the same without loading or starting anything, and resolves once the route cleared the cookie (it rejects with `network_connection` or `server_error` when it couldn't, and `not_in_browser` on the server). Call `start()` again to identify once consent is back.
|
|
115
|
+
|
|
116
|
+
```ts
|
|
117
|
+
let zeno: Zeno | undefined
|
|
118
|
+
|
|
119
|
+
consentTool.onChange(async ({ fraudPrevention }) => {
|
|
120
|
+
if (fraudPrevention) {
|
|
121
|
+
zeno ??= start('/zeno')
|
|
122
|
+
} else if (zeno) {
|
|
123
|
+
zeno.stop()
|
|
124
|
+
zeno = undefined
|
|
125
|
+
} else {
|
|
126
|
+
await forget('/zeno')
|
|
127
|
+
}
|
|
128
|
+
})
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### Errors
|
|
132
|
+
|
|
133
|
+
`identify()` never rejects. When nothing was identified it resolves `{ requestId: undefined, error }`, with `error` a `ZenoError` whose `code` is one of these (`ZenoErrorCode`), and whose `message` says more where there's more to say. For all of them the action can go on without a request ID: your server's `verify` answers `challenge` with `no-request-id`, so it decides. `start()` itself throws a `ZenoError` for options it can't use (`invalid_options`).
|
|
134
|
+
|
|
135
|
+
```ts
|
|
136
|
+
// Never throws: requestId is undefined when nothing was identified
|
|
137
|
+
const { requestId, error } = await zeno.identify({ action: 'login' })
|
|
138
|
+
|
|
139
|
+
if (error) {
|
|
140
|
+
console.warn('Identification failed', error.code, error.message)
|
|
141
|
+
}
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
| Code | What happened | What to do |
|
|
145
|
+
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
|
|
146
|
+
| `client_timeout` | Zeno didn't answer in time. | Go on without a request ID. |
|
|
147
|
+
| `network_connection` | The route couldn't be reached, or the request was cut off. | Go on without a request ID. |
|
|
148
|
+
| `csp_block` | The page's Content Security Policy blocked the script's code (`script-src`) or the identification (`connect-src`). | Allow the route's origin in both (see Content Security Policy). |
|
|
149
|
+
| `insecure_context` | The page isn't a secure context (https or localhost), which the script needs for its random ids and hashes. | Serve the page over https. |
|
|
150
|
+
| `collection_failed` | The browser data couldn't be collected at all, as when an extension broke the browser's basics. | Go on without a request ID. |
|
|
151
|
+
| `invalid_options` | An option `start()` or `identify()` can't use (a route path that isn't on this site, a bad external id or metadata), or one Zeno refused; the message names it. | Fix the option. |
|
|
152
|
+
| `script_load_failed` | The script couldn't be loaded from the route: nothing answers there (your site's own 404 page), something other than the script does, or the network failed. The message names the url and the status. | Check the route answers at its path; meanwhile go on without a request ID. |
|
|
153
|
+
| `server_error` | The route or Zeno failed, or answered something that isn't the route's JSON. The message says what: a route that wasn't given the visitor's IP says to pass it, a refused API key says to check the route's. | Read the message and the route's server log; go on without a request ID. |
|
|
154
|
+
| `account_closed` | Zeno closed the organization's account (as for unpaid invoices): identification is refused until it's reopened. | Contact support. |
|
|
155
|
+
| `stopped` | `stop()` was called, before or during the `identify()`. | Call `start()` again once consent is back. |
|
|
156
|
+
| `capped` | A limit stopped the identification: a spend limit you set, the key's ceiling or the visitor ip's rate limit. Not a bot. | Go on without a request ID. |
|
|
157
|
+
| `not_in_browser` | `identify()` ran on the server, while a page rendered. | Call it in the action's handler in the browser. |
|
|
158
|
+
|
|
159
|
+
### What it collects
|
|
160
|
+
|
|
161
|
+
- **The device and browser:** technical characteristics of the hardware and software, like the screen, the browser's settings, its languages and time zone.
|
|
162
|
+
- **Integrity checks:** whether a script drives the browser and whether what it reports fits together.
|
|
163
|
+
- **With the request:** the page url and referrer without their query string and fragment. Your route adds the request's headers (the user agent among them, never other cookies or authorization headers) and the visitor's ip.
|
|
164
|
+
|
|
165
|
+
It reads no personal content, like names, messages or what people type, and nothing from other sites. The report is about a kilobyte.
|
|
166
|
+
|
|
167
|
+
### Without a bundler
|
|
168
|
+
|
|
169
|
+
A page without a build step can import `start` from the route itself, which serves the script as an ES module:
|
|
170
|
+
|
|
171
|
+
<!-- prettier-ignore -->
|
|
172
|
+
```html
|
|
173
|
+
<button id="login">Log in</button>
|
|
174
|
+
<script type="module">
|
|
175
|
+
import { start } from '/zeno' // your route's path
|
|
176
|
+
|
|
177
|
+
const zeno = start()
|
|
178
|
+
|
|
179
|
+
document.querySelector('#login').addEventListener('click', async () => {
|
|
180
|
+
const { requestId } = await zeno.identify({ action: 'login' })
|
|
181
|
+
|
|
182
|
+
await fetch('/api/login', {
|
|
183
|
+
method: 'POST',
|
|
184
|
+
headers: { 'Content-Type': 'application/json' },
|
|
185
|
+
body: JSON.stringify({ email, password, requestId }),
|
|
186
|
+
})
|
|
187
|
+
})
|
|
188
|
+
</script>
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
That `start()` takes the path it was imported from unless you pass another, and answers the same `identify()` and `stop()` with the same error codes. What it can't do is report a script that doesn't load: the `import` itself fails, without `script_load_failed` or `csp_block`, and there's no `forget()`. Use `zeno.id` where you can.
|
|
192
|
+
|
|
193
|
+
## Proxy route
|
|
194
|
+
|
|
195
|
+
The browser SDK never talks to Zeno directly. It loads its script from a route on your own site and sends its identifications there, and the route passes them on with your API key and the visitor's IP.
|
|
196
|
+
|
|
197
|
+
- Ad and tracker blockers block requests to identification services. A path on your own site looks like any other request your pages make.
|
|
198
|
+
- The route keeps the visitor id in a first-party `HttpOnly` cookie (`zeno_id`) that it sets itself, which Safari keeps for a year where it would delete a script's storage after 7 days.
|
|
199
|
+
- Your API key stays on your server, and the route refuses a browser's cross-site request, so there's no allow list of origins to keep.
|
|
200
|
+
|
|
201
|
+
`createProxy(apiKey, options?)` returns the route's handler: `zeno(request, ip)` takes a standard `Request` and the IP address it came from, and returns a `Response`, using web APIs only. The browser SDK calls it with two methods on one path: `GET` loads the script (gzipped when the browser takes it; `HEAD` too), and `POST` identifies, or, as `forget()`, clears the visitor id for withdrawn consent.
|
|
202
|
+
|
|
203
|
+
```ts
|
|
204
|
+
// ip: the IP address the request came from, as your server gives it
|
|
205
|
+
export const handle = (request: Request, ip: string) => {
|
|
206
|
+
if (new URL(request.url).pathname === '/zeno') {
|
|
207
|
+
// the path you chose
|
|
208
|
+
return zeno(request, ip)
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
// …the rest of your app
|
|
212
|
+
}
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
```ts
|
|
216
|
+
// Express, Fastify or Node's http server
|
|
217
|
+
import { nodeHandler } from 'zeno.id/server/node'
|
|
218
|
+
|
|
219
|
+
// behind a proxy: app.set('trust proxy', 1)
|
|
220
|
+
app.all('/zeno', nodeHandler(zeno)) // the path you chose
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
```ts
|
|
224
|
+
// app/zeno/route.ts
|
|
225
|
+
import { zeno } from '@/lib/zeno'
|
|
226
|
+
|
|
227
|
+
// X-Real-IP: set by Vercel, or by your own proxy (nginx: proxy_set_header X-Real-IP $remote_addr;)
|
|
228
|
+
const handler = (request: Request) => zeno(request, request.headers.get('x-real-ip'))
|
|
229
|
+
|
|
230
|
+
// Next.js calls the export named after the method
|
|
231
|
+
export const GET = handler
|
|
232
|
+
export const POST = handler
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
```ts
|
|
236
|
+
// Bun.serve
|
|
237
|
+
Bun.serve({
|
|
238
|
+
routes: {
|
|
239
|
+
'/zeno': (request, server) => zeno(request, server.requestIP(request)?.address),
|
|
240
|
+
},
|
|
241
|
+
})
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
```ts
|
|
245
|
+
import { env } from 'cloudflare:workers'
|
|
246
|
+
// A Cloudflare Worker
|
|
247
|
+
import { createProxy } from 'zeno.id/server'
|
|
248
|
+
|
|
249
|
+
// Your proxy route: the browser SDK talks to Zeno through it
|
|
250
|
+
const zeno = createProxy(env.ZENO_API_KEY)
|
|
251
|
+
|
|
252
|
+
export default {
|
|
253
|
+
fetch: (request: Request) =>
|
|
254
|
+
new URL(request.url).pathname === '/zeno'
|
|
255
|
+
? zeno(request, request.headers.get('cf-connecting-ip'))
|
|
256
|
+
: fetch(request),
|
|
257
|
+
}
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
The docs' quickstart has SvelteKit, Nuxt, React Router, SolidStart, Astro and Hono too.
|
|
261
|
+
|
|
262
|
+
| Option | |
|
|
263
|
+
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
264
|
+
| `cookiePath` | The path the browser calls the route on, when something in front of the handler rewrites it (the browser calls `/zeno`, a handler at `/api/proxy` answers); by default the request's. |
|
|
265
|
+
| `apiUrl` | Only for another Zeno API than the live one, like a staging deployment. |
|
|
266
|
+
|
|
267
|
+
The route forwards your visitors' headers by name only, apart from the values Zeno reads (`User-Agent`, `Origin`, `Signature-Agent`, `Signature-Input`), so your cookies and credentials never leave your server.
|
|
268
|
+
|
|
269
|
+
### The visitor's IP
|
|
270
|
+
|
|
271
|
+
Pass the IP address the request came from: your framework's client IP. Behind a proxy of your own, turn on your framework's trust-proxy setting so it's the visitor's. The route uses the IP as given and reads no header for it; without one, an identification answers `500 server_error` saying to pass it, which the browser SDK passes on. `nodeHandler` (from `zeno.id/server/node`, which alone uses Node's types) passes Express's and Fastify's `req.ip`, else the socket's address.
|
|
272
|
+
|
|
273
|
+
The route checks a `POST` before it calls Zeno: a JSON body of at most 128 KB with a `browserData` object, and no `Sec-Fetch-Site: cross-site`. Anything else gets a `400 invalid_request` and costs nothing. Zeno's errors reach the browser with their status and code; a `401` (the route's API key is wrong) is logged with Zeno's message and the browser only gets the code. When Zeno can't be reached within 10 seconds, or something else answers in its place, the route logs it and answers `502`.
|
|
274
|
+
|
|
275
|
+
## Verify
|
|
276
|
+
|
|
277
|
+
`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.
|
|
278
|
+
|
|
279
|
+
| Answer | When |
|
|
280
|
+
| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
281
|
+
| `{ action: 'challenge', reasons: ['no-request-id'] }` | `requestId` is `undefined`, `null` or empty: the browser sent none (its identification failed, was blocked or capped, or a bot never ran the script). |
|
|
282
|
+
| `{ action: 'block', reasons: ['not-found'] }` | No such event: a forged request ID, or another project's. |
|
|
283
|
+
| `{ action: 'block', reasons: ['already-used'], event }` | The request ID was verified before: an action's request sent again, or a captured request ID. |
|
|
284
|
+
| `{ action: 'block', reasons: ['ip-mismatch'], event }` | The event came from another ip (for IPv6 another /64; IPv4 and IPv6 are never compared): a request ID captured and sent elsewhere. |
|
|
285
|
+
| `{ action: 'block', reasons: ['too-old'], event }` | The event is older than `maxAge` seconds, 300 (5 minutes) by default. |
|
|
286
|
+
| `{ action: 'block', reasons: ['external-id-mismatch'], event }` | The event has another external ID than the one you passed: another user's identification. One without an external ID is fine. |
|
|
287
|
+
| the event's `verdict`, with the `event` | Otherwise: `allow`, `challenge` or `block`, and the signals behind it. |
|
|
288
|
+
|
|
289
|
+
`ip-mismatch`, `too-old` and `external-id-mismatch` come together when several fail, and leave the request ID unused, so a request ID sent from elsewhere doesn't use up the visitor's own. The verdict comes from the event's risk score and bot verdict: `block` for a bad bot or a risk score of 15 or more, `challenge` from 9 to 14, else `allow`; its `reasons` are the detected signals that scored, strongest first, and `bad-bot`.
|
|
290
|
+
|
|
291
|
+
Call it after the action succeeded (the password matched, the account exists), with the user's ID as `externalId`: Zeno records it on an event that has none, so a signup needs no other call and a failed login attaches nothing. It writes nothing else but the request ID's use.
|
|
292
|
+
|
|
293
|
+
```ts
|
|
294
|
+
// At a signup, once the account exists:
|
|
295
|
+
const { action } = await client.verify(requestId, {
|
|
296
|
+
externalId: account.id,
|
|
297
|
+
})
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
`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`.
|
|
301
|
+
|
|
302
|
+
## Server API
|
|
303
|
+
|
|
304
|
+
```ts
|
|
305
|
+
import { client } from './zeno' // made next to your proxy route
|
|
306
|
+
|
|
307
|
+
const event = await client.getEvent(requestId)
|
|
308
|
+
const { items, cursor } = await client.searchEvents({
|
|
309
|
+
externalId: user.id,
|
|
310
|
+
signal: 'vpn',
|
|
311
|
+
})
|
|
312
|
+
// Several values match any of them
|
|
313
|
+
const risky = await client.searchEvents({
|
|
314
|
+
country: ['US', 'DE'],
|
|
315
|
+
signal: ['vpn', 'tor'],
|
|
316
|
+
})
|
|
317
|
+
await client.deleteExternalId(user.id)
|
|
318
|
+
|
|
319
|
+
// Related accounts: add what only you know
|
|
320
|
+
await client.addRelation({
|
|
321
|
+
externalId: user.id,
|
|
322
|
+
type: 'phone',
|
|
323
|
+
value: order.phone,
|
|
324
|
+
action: 'checkout',
|
|
325
|
+
})
|
|
326
|
+
await client.addRelation({
|
|
327
|
+
externalId: user.id,
|
|
328
|
+
type: 'referral',
|
|
329
|
+
relatedExternalId: referrer.id,
|
|
330
|
+
at: user.createdAt,
|
|
331
|
+
})
|
|
332
|
+
const { duplicate, identified } = await client.getRelatedValues(user.id)
|
|
333
|
+
const { externalIds } = await client.getRelated(user.id, { depth: 2 })
|
|
334
|
+
|
|
335
|
+
// For your admin panel's user page, one per view
|
|
336
|
+
const { url } = await client.createEmbed({
|
|
337
|
+
externalId: user.id,
|
|
338
|
+
origin: 'https://admin.example.com',
|
|
339
|
+
})
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
| Method | Call |
|
|
343
|
+
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
344
|
+
| `verify(requestId, { ip?, externalId?, maxAge? }?)` | `POST /verify` |
|
|
345
|
+
| `getEvent(requestId)` | `GET /events/{requestId}` |
|
|
346
|
+
| `searchEvents(filters)` | `GET /events?...` |
|
|
347
|
+
| `getVisitor(visitorId)` | `GET /visitors/{visitorId}` |
|
|
348
|
+
| `deleteVisitor(visitorId)` | `DELETE /visitors/{visitorId}` |
|
|
349
|
+
| `deleteExternalId(externalId)` | `DELETE /external-ids?externalId=...` |
|
|
350
|
+
| `addRelation({ externalId, type, value or relatedExternalId, action?, at? })` | `POST /related` |
|
|
351
|
+
| `removeRelation({ externalId, type, value or relatedExternalId })` | `DELETE /related?externalId=...&type=...`, `{ removed }`, free |
|
|
352
|
+
| `getRelated(externalId, { type?, depth? })` | `GET /related?externalId=...`, every type unless `type` names one |
|
|
353
|
+
| `getRelatedValues(externalId, { type? })` | `GET /related/values?externalId=...` |
|
|
354
|
+
| `lookupRelated(type, value, { limit?, cursor? })` | `GET /related/lookup?type=...&value=...`, 20 a page by default (up to 100) |
|
|
355
|
+
| `getSharedValues(type, { limit?, cursor? })` | `GET /related/shared?type=...` |
|
|
356
|
+
| `createEmbed({ externalId, origin, ttl? })` | `POST /embeds` |
|
|
357
|
+
|
|
358
|
+
A list filter (`apiKeyId`, `country`, `origin`, `asn`, `browser`, `os`, `action`, `signal`, `bot`) takes an array and matches any of its values. Visitor ids and ips relate your users by themselves for events with an external id; `addRelation` adds what only you know: an ip seen elsewhere, a value of a type of your own, or a relation between two users. Make a `createEmbed` link for each view of your admin panel's page.
|
|
359
|
+
|
|
360
|
+
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.
|
|
361
|
+
|
|
362
|
+
The SDK's own codes: `network_error` (status `0`) when the API can't be reached or doesn't answer within 10 seconds, never retried; `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).
|
|
363
|
+
|
|
364
|
+
`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.
|
|
365
|
+
|
|
366
|
+
`addRelation`'s `at` takes a `Date`, epoch milliseconds or an ISO string. A type's first call fixes whether it holds values or relations. The project's settings hold each type's weight (`visitor-id` 0.8, `ip` 0.4, a type of your own 0.5 by default), applied when relations are read, so a change re-scores every relation. The reads answer each value's `weight` and each related user's (what the two share combined as `1 - Π(1 - weight)`, so two shared ips make 0.64 and a browser and an ip 0.88, multiplied along the path); `duplicate` means they share one value weighing 0.5 or more with another user. `createEmbed` answers `{ url, expiresAt }`: put the url in an iframe on `origin`, the only page allowed to frame it, before `expiresAt` (`ttl`, 5 to 60 minutes, 15 by default).
|
|
367
|
+
|
|
368
|
+
## Webhooks
|
|
369
|
+
|
|
370
|
+
```ts
|
|
371
|
+
import { verifyWebhook } from 'zeno.id/server'
|
|
372
|
+
|
|
373
|
+
// POST /webhooks/zeno: any runtime with web Request and Response
|
|
374
|
+
export const handle = async (request: Request) => {
|
|
375
|
+
// The raw body: the signature covers the exact bytes
|
|
376
|
+
const body = await request.text()
|
|
377
|
+
const event = await verifyWebhook(body, request.headers.get('zeno-signature'), process.env.ZENO_WEBHOOK_SECRET)
|
|
378
|
+
|
|
379
|
+
if (!event) {
|
|
380
|
+
return new Response(null, { status: 400 })
|
|
381
|
+
}
|
|
382
|
+
|
|
383
|
+
return new Response(null, { status: 204 })
|
|
384
|
+
}
|
|
385
|
+
```
|
|
386
|
+
|
|
387
|
+
`verifyWebhook` resolves to the event when the signature matched, a `WebhookEvent` (the event without its `velocity`), else to `undefined`. In Express, read the raw body with `express.text({ type: 'application/json' })`. Pass the raw body: the signature covers it byte for byte. Deliveries older than 5 minutes (`tolerance`, in seconds) are refused, so a captured one can't be replayed. The header is `t=<unix seconds>,v1=<hmac sha256 hex>`; spaces after the commas and several `v1=` signatures are accepted: for 24 hours after a secret rotation every delivery carries one signed with the new secret and one with the previous. Each delivery also has `Zeno-Delivery-Id` (the same on every retry, to drop one you handled) and `Zeno-Trigger` (`event`, `update`, `redeliver` or `test`; a test sends the project's latest event or a made up one, so don't act on it).
|
|
388
|
+
|
|
389
|
+
## Sealed results
|
|
390
|
+
|
|
391
|
+
```ts
|
|
392
|
+
import { unsealResult } from 'zeno.id/server'
|
|
393
|
+
|
|
394
|
+
const { action, reasons } = await unsealResult(sealedResult, {
|
|
395
|
+
key: process.env.ZENO_ENCRYPTION_KEY,
|
|
396
|
+
ip, // the same IP your proxy route got
|
|
397
|
+
externalId: user.id,
|
|
398
|
+
})
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
A project with sealed results gives the browser an encrypted copy of the event, for a server that can't wait for an API call. A sealed result can't be forged: only Zeno can make one that decrypts with your key. But it comes from the browser, so the same one can be sent again within a few minutes. `unsealResult(sealed, { key, ip?, externalId?, maxAge? })` answers like `verify`, `{ action, reasons, event? }`: `challenge` with `no-request-id` for none, `block` with `not-found` for one that doesn't open (changed, or sealed with another key), `ip-mismatch` from another IP than `ip` (compared as `verify` does), `too-old` past `maxAge` (300 seconds by default), `external-id-mismatch` for another user's, else the event's verdict. If a repeat matters for the action, use `verify`, which allows each request ID once. While you replace the key, pass both, `key: [current, previous]`: each is tried in order. It rejects with a TypeError for a key that isn't one (missing, hex, the wrong length), and an Error for one that opens but isn't an event.
|
|
402
|
+
|
|
403
|
+
## License
|
|
404
|
+
|
|
405
|
+
MIT, see `LICENSE`.
|