@fingerly/next 0.2.0 → 0.3.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 +344 -111
- package/dist/index.cjs +3 -3
- package/dist/index.d.cts +13 -5
- package/dist/index.d.ts +13 -5
- package/dist/index.js +6 -4
- package/dist/server.d.cts +7 -0
- package/dist/server.d.ts +7 -0
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,23 +1,112 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://fingerly.io">
|
|
3
|
+
<picture>
|
|
4
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/fingerly-io/.github/main/assets/logo-dark.svg">
|
|
5
|
+
<img src="https://raw.githubusercontent.com/fingerly-io/.github/main/assets/logo-light.svg" alt="Fingerly" height="44">
|
|
6
|
+
</picture>
|
|
7
|
+
</a>
|
|
8
|
+
</p>
|
|
9
|
+
|
|
10
|
+
<p align="center"><b>Fingerly for Next.js</b><br>The React binding, with Next's configuration, client boundary and Server Action handling built in.</p>
|
|
11
|
+
|
|
12
|
+
<p align="center">
|
|
13
|
+
<a href="https://www.npmjs.com/package/@fingerly/next"><img src="https://img.shields.io/npm/v/@fingerly/next?style=flat-square" alt="npm version"></a>
|
|
14
|
+
<a href="https://www.npmjs.com/package/@fingerly/next"><img src="https://img.shields.io/npm/dm/@fingerly/next?style=flat-square" alt="npm downloads"></a>
|
|
15
|
+
<a href="https://github.com/fingerly-io/sdks/blob/main/client/web/next/LICENSE"><img src="https://img.shields.io/npm/l/@fingerly/next?style=flat-square" alt="Apache-2.0 licence"></a>
|
|
16
|
+
<img src="https://img.shields.io/badge/next.js-15%2B-blue?style=flat-square" alt="Next.js 15 or newer">
|
|
17
|
+
</p>
|
|
18
|
+
|
|
19
|
+
<p align="center"><img src="https://raw.githubusercontent.com/fingerly-io/.github/main/assets/banner.webp" alt="Fingerly" width="100%"></p>
|
|
20
|
+
|
|
21
|
+
## What is this
|
|
22
|
+
|
|
23
|
+
`@fingerly/next` is the Next.js integration. It wraps
|
|
24
|
+
[`@fingerly/react`](https://www.npmjs.com/package/@fingerly/react) and adds the
|
|
25
|
+
three things that are actually about Next: where the configuration comes from,
|
|
26
|
+
where the client boundary sits, and how an identification reaches a Server
|
|
27
|
+
Action. [Fingerly](https://fingerly.io) helps you protect signups, logins and
|
|
28
|
+
payments from fraud and abuse.
|
|
29
|
+
|
|
30
|
+
> **Not for apps.** This binding runs the browser SDK, which collects nothing
|
|
31
|
+
> that identifies the device inside an app's web view (`WKWebView`, Android
|
|
32
|
+
> `WebView`, Capacitor, Cordova, Ionic, React Native WebView, Flutter WebView,
|
|
33
|
+
> Electron) and answers there with an empty `visitorId`. Use the Fingerly iOS or
|
|
34
|
+
> Android SDK, or the React Native, Flutter or Lynx bridge, in an app; see
|
|
35
|
+
> section 3.3 of the
|
|
36
|
+
> [privacy notes](https://github.com/fingerly-io/sdks/blob/main/docs/privacy.md).
|
|
37
|
+
|
|
38
|
+
## Getting started
|
|
39
|
+
|
|
40
|
+
1. **Get a key.** Create a public SDK key in the dashboard
|
|
41
|
+
([how keys work](https://docs.fingerly.io/docs/api-keys)).
|
|
42
|
+
2. **Install.**
|
|
43
|
+
|
|
44
|
+
```sh
|
|
45
|
+
npm install @fingerly/next
|
|
46
|
+
# or: pnpm add @fingerly/next
|
|
47
|
+
# or: yarn add @fingerly/next
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
3. **Add the provider, then identify.**
|
|
51
|
+
|
|
52
|
+
```tsx
|
|
53
|
+
// app/layout.tsx (a Server Component)
|
|
54
|
+
import { FingerlyProvider } from '@fingerly/next'
|
|
55
|
+
|
|
56
|
+
export default function RootLayout({ children }: { children: React.ReactNode }) {
|
|
57
|
+
return (
|
|
58
|
+
<html>
|
|
59
|
+
<body>
|
|
60
|
+
{/* consent="granted" only once you have consent (or know none is required here; see Consent below) */}
|
|
61
|
+
<FingerlyProvider apiKey={process.env.FINGERLY_API_KEY} consent="granted">
|
|
62
|
+
{children}
|
|
63
|
+
</FingerlyProvider>
|
|
64
|
+
</body>
|
|
65
|
+
</html>
|
|
66
|
+
)
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
```tsx
|
|
71
|
+
'use client'
|
|
72
|
+
import { useIdentify } from '@fingerly/next'
|
|
73
|
+
|
|
74
|
+
export function Checkout() {
|
|
75
|
+
const { identify, isLoading } = useIdentify()
|
|
76
|
+
…
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
4. **Decide on your backend.** Send the `requestId` that `await identify()`
|
|
81
|
+
resolves with to your server and act on its decision; see
|
|
82
|
+
[Decide on your backend](#decide-on-your-backend).
|
|
2
83
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
Server Action.
|
|
7
|
-
|
|
8
|
-
Requires Next **15 or newer** and React **19** (App Router or Pages Router).
|
|
9
|
-
Tested against Next 16.
|
|
10
|
-
|
|
11
|
-
```
|
|
12
|
-
pnpm add @fingerly/next
|
|
13
|
-
```
|
|
84
|
+
The package is marked `'use client'`, so the provider is a client boundary and
|
|
85
|
+
your layout does not have to become one. Pages Router is the same component in
|
|
86
|
+
`_app.tsx`.
|
|
14
87
|
|
|
15
|
-
|
|
16
|
-
inside an app's web view (Capacitor, Cordova, Ionic, React Native WebView,
|
|
17
|
-
`WKWebView`, Android `WebView`, Electron). Use the Fingerly iOS or Android SDK
|
|
18
|
-
in an app; see [docs/privacy.md §3.3](../../../docs/privacy.md).
|
|
88
|
+
Mounting it collects nothing. When to identify stays the page's decision.
|
|
19
89
|
|
|
20
|
-
##
|
|
90
|
+
## Contents
|
|
91
|
+
|
|
92
|
+
- [Configure the key](#configure-the-key)
|
|
93
|
+
- [Identify](#identify)
|
|
94
|
+
- [Consent](#consent)
|
|
95
|
+
- [First-party endpoints](#first-party-endpoints)
|
|
96
|
+
- [Options](#options)
|
|
97
|
+
- [Carry it into a Server Action](#carry-it-into-a-server-action)
|
|
98
|
+
- [Decide on your backend](#decide-on-your-backend)
|
|
99
|
+
- [The two entries](#the-two-entries)
|
|
100
|
+
- [Errors](#errors)
|
|
101
|
+
- [What this does not do](#what-this-does-not-do)
|
|
102
|
+
- [More](#more)
|
|
103
|
+
- [TypeScript](#typescript)
|
|
104
|
+
- [Requirements](#requirements)
|
|
105
|
+
- [Documentation](#documentation)
|
|
106
|
+
- [Help](#help)
|
|
107
|
+
- [Licence](#licence)
|
|
108
|
+
|
|
109
|
+
## Configure the key
|
|
21
110
|
|
|
22
111
|
Read the key in a Server Component and pass it down:
|
|
23
112
|
|
|
@@ -46,41 +135,56 @@ Either way the key is a **public** SDK key, scoped to the origins you list
|
|
|
46
135
|
against it. A **secret** key is refused by the API whenever a request carries
|
|
47
136
|
an `Origin`, so the mistake either route invites cannot silently work.
|
|
48
137
|
|
|
49
|
-
##
|
|
138
|
+
## Identify
|
|
139
|
+
|
|
140
|
+
The hooks are `@fingerly/react`'s, re-exported so you install one package
|
|
141
|
+
(`useIdentify`, `useFingerly`, `createFingerlyStore`):
|
|
50
142
|
|
|
51
143
|
```tsx
|
|
52
|
-
|
|
53
|
-
import {
|
|
144
|
+
'use client'
|
|
145
|
+
import { useIdentify } from '@fingerly/next'
|
|
54
146
|
|
|
55
|
-
export
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
<body>
|
|
59
|
-
{/* consent="granted" only once you have consent (or know none is required here; see docs/privacy.md §4) */}
|
|
60
|
-
<FingerlyProvider apiKey={process.env.FINGERLY_API_KEY} consent="granted">
|
|
61
|
-
{children}
|
|
62
|
-
</FingerlyProvider>
|
|
63
|
-
</body>
|
|
64
|
-
</html>
|
|
65
|
-
)
|
|
147
|
+
export function Checkout() {
|
|
148
|
+
const { identify, isLoading } = useIdentify()
|
|
149
|
+
…
|
|
66
150
|
}
|
|
67
151
|
```
|
|
68
152
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
`
|
|
153
|
+
Send the `requestId` that `await identify()` resolves with to your backend and
|
|
154
|
+
act on its decision (see [Decide on your backend](#decide-on-your-backend)).
|
|
155
|
+
`isSuspicious`, `suspectScore` and `suspectLevel` are a UI hint only; never gate
|
|
156
|
+
an action on them in the page.
|
|
72
157
|
|
|
73
|
-
|
|
158
|
+
`identify()` runs one collection pass (a 350 ms budget by default) and posts
|
|
159
|
+
once, in a single round trip to `POST /api/v1/ingest`, resolving with the
|
|
160
|
+
server's answer: `requestId`, `visitorId`, `identifiable`, and `suspectScore`
|
|
161
|
+
and `suspectLevel` unless the key hides them. Each report carries a single-use
|
|
162
|
+
freshness ticket held in memory only; when none is held, the ticket request
|
|
163
|
+
runs in parallel with collection and never holds up or fails `identify()`.
|
|
74
164
|
|
|
75
|
-
|
|
76
|
-
`
|
|
77
|
-
|
|
165
|
+
`visitorId` is `""` (and `visitorIsNew` is `false`) whenever `identifiable` is
|
|
166
|
+
`false`, inside an app's web view, or when the server declines to name a
|
|
167
|
+
high-risk visitor it has not seen before. To inspect the raw `SignalReport`
|
|
168
|
+
locally without submitting anything, call
|
|
169
|
+
`(await useFingerly().client()).collect()`.
|
|
170
|
+
|
|
171
|
+
`useIdentify({ immediate: true })` is safe in a Next app for the reason it is
|
|
172
|
+
safe anywhere: it runs in an effect, and effects do not run during a server
|
|
173
|
+
render. The page renders on the server, collects after hydration, and every
|
|
174
|
+
component that asks shares the one identification.
|
|
78
175
|
|
|
79
|
-
|
|
176
|
+
The full surface (`immediate`, `suspend`, `tag`, `incognitoDetection`,
|
|
177
|
+
`refresh`, and everything you get back) is documented in the
|
|
178
|
+
[React binding's README](https://github.com/fingerly-io/sdks/tree/main/client/web/react#readme).
|
|
80
179
|
|
|
81
|
-
Consent
|
|
82
|
-
|
|
83
|
-
|
|
180
|
+
## Consent
|
|
181
|
+
|
|
182
|
+
Consent defaults to `pending`, and nothing is collected or sent until it is
|
|
183
|
+
`granted`. A site with a consent banner passes the banner's answer instead of
|
|
184
|
+
`"granted"`. When identification needs the visitor's consent first, pass
|
|
185
|
+
`consent` with what your consent tool says now. It is a prop rather than an
|
|
186
|
+
environment variable, because it is the visitor's decision rather than the
|
|
187
|
+
deployment's:
|
|
84
188
|
|
|
85
189
|
```tsx
|
|
86
190
|
'use client'
|
|
@@ -95,29 +199,66 @@ While it is not `granted` nothing is collected or sent,
|
|
|
95
199
|
`useIdentify({ immediate: true })` and `<FingerlyRequestId />` wait, and a
|
|
96
200
|
manual `identify()` fails with a `ConsentError`. Once it becomes `granted` the
|
|
97
201
|
waiting identification runs, once. The details are in the
|
|
98
|
-
[React binding's README](
|
|
202
|
+
[React binding's README](https://github.com/fingerly-io/sdks/tree/main/client/web/react#consent).
|
|
99
203
|
|
|
100
|
-
|
|
204
|
+
Pass `granted` only once you have consent, or know none is required here. See
|
|
205
|
+
section 4 of the
|
|
206
|
+
[privacy notes](https://github.com/fingerly-io/sdks/blob/main/docs/privacy.md),
|
|
207
|
+
[privacy and consent](https://docs.fingerly.io/docs/privacy-and-consent) and
|
|
208
|
+
[consent tools](https://docs.fingerly.io/docs/consent-tools).
|
|
101
209
|
|
|
102
|
-
|
|
210
|
+
## First-party endpoints
|
|
103
211
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
212
|
+
Serving the SDK's submissions from your own origin is what gets them past
|
|
213
|
+
content blockers. The proxy for it lives in `@fingerly/node`, because it holds a
|
|
214
|
+
server secret and has to forward the visitor's real address rather than your
|
|
215
|
+
server's. Create a proxy in the dashboard, put it in the route file for the path
|
|
216
|
+
it issued, and give the provider `endpoints="/k7x2qm4a"`:
|
|
107
217
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
218
|
+
```ts
|
|
219
|
+
// app/k7x2qm4a/route.ts
|
|
220
|
+
import { Fingerly } from '@fingerly/node'
|
|
221
|
+
|
|
222
|
+
// Built on the first request rather than at import, so `next build` does not
|
|
223
|
+
// need the proxy key.
|
|
224
|
+
let proxy: ((request: Request) => Promise<Response>) | undefined
|
|
225
|
+
|
|
226
|
+
export function POST(request: Request) {
|
|
227
|
+
proxy ??= Fingerly.createProxy({
|
|
228
|
+
proxyKey: process.env.FINGERLY_PROXY_KEY!,
|
|
229
|
+
// The last X-Forwarded-For entry is the address your own server or load
|
|
230
|
+
// balancer saw. Read a CDN's client-IP header instead only when traffic
|
|
231
|
+
// can reach this app through that CDN alone.
|
|
232
|
+
clientIp: (req) => req.headers.get('x-forwarded-for')?.split(',').at(-1)?.trim() ?? '',
|
|
233
|
+
})
|
|
234
|
+
return proxy(request)
|
|
111
235
|
}
|
|
112
236
|
```
|
|
113
237
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
238
|
+
Pass the path as a string. An array works too, and is compared by its
|
|
239
|
+
contents, so `endpoints={['/k7x2qm4a']}` does not start a new identification
|
|
240
|
+
when the layout renders again.
|
|
241
|
+
|
|
242
|
+
`@fingerly/next/server` also re-exports the proxy factory from `@fingerly/node`
|
|
243
|
+
as `createFingerlyProxy` (with its `FingerlyProxyOptions` type). See
|
|
244
|
+
[proxy integrations](https://docs.fingerly.io/docs/proxy-integrations) and the
|
|
245
|
+
[Node SDK](https://docs.fingerly.io/docs/sdks/node).
|
|
118
246
|
|
|
119
|
-
|
|
120
|
-
|
|
247
|
+
## Options
|
|
248
|
+
|
|
249
|
+
`<FingerlyProvider>` props:
|
|
250
|
+
|
|
251
|
+
| Prop | Type | Notes |
|
|
252
|
+
| --- | --- | --- |
|
|
253
|
+
| `apiKey` | `string` | A public SDK key. Overrides `NEXT_PUBLIC_FINGERLY_API_KEY`. |
|
|
254
|
+
| `endpoints` | `string \| string[]` | Ordered first-party ingestion paths or URLs, compared by contents. Overrides `NEXT_PUBLIC_FINGERLY_ENDPOINTS`, which is a JSON array of strings. |
|
|
255
|
+
| `fallbackToDefaultEndpoint` | `boolean` | Opt into the Fingerly API after the custom endpoints fail. |
|
|
256
|
+
| `consent` | `'pending' \| 'granted' \| 'denied'` | Defaults to `pending`. Never read from the environment. |
|
|
257
|
+
| `incognitoDetection` | `'standard' \| 'extended'` | Defaults to `standard`, which checks for private browsing without writing to the visitor's storage; `extended` adds a further check on Chromium browsers inside the same budget. |
|
|
258
|
+
| `apiVersion` | `string` | API route version. Defaults to `v1`. |
|
|
259
|
+
|
|
260
|
+
`<FingerlyRequestId />` takes `name` (the field name), `tag` and `immediate`
|
|
261
|
+
(on by default). The remaining options are `@fingerly/react`'s.
|
|
121
262
|
|
|
122
263
|
## Carry it into a Server Action
|
|
123
264
|
|
|
@@ -129,11 +270,13 @@ travel with the submission:
|
|
|
129
270
|
import { FingerlyRequestId } from '@fingerly/next'
|
|
130
271
|
import { signUp } from './actions'
|
|
131
272
|
|
|
132
|
-
|
|
273
|
+
// attemptId: a random value your server issued for this form and keeps in the
|
|
274
|
+
// visitor's session (for example in an HttpOnly cookie).
|
|
275
|
+
export default function Page({ attemptId }: { attemptId: string }) {
|
|
133
276
|
return (
|
|
134
277
|
<form action={signUp}>
|
|
135
278
|
<input name="email" />
|
|
136
|
-
<FingerlyRequestId />
|
|
279
|
+
<FingerlyRequestId tag={`signup:${attemptId}`} />
|
|
137
280
|
<button>Create account</button>
|
|
138
281
|
</form>
|
|
139
282
|
)
|
|
@@ -143,94 +286,184 @@ export default function Page() {
|
|
|
143
286
|
```ts
|
|
144
287
|
// app/signup/actions.ts
|
|
145
288
|
'use server'
|
|
289
|
+
import { cookies, headers } from 'next/headers'
|
|
146
290
|
import { readRequestId } from '@fingerly/next/server'
|
|
291
|
+
import { decide } from '@/lib/fingerly' // the check below
|
|
147
292
|
|
|
148
293
|
export async function signUp(formData: FormData) {
|
|
149
294
|
const requestId = readRequestId(formData)
|
|
150
|
-
|
|
295
|
+
if (!requestId) return { error: 'Please try again.' }
|
|
296
|
+
|
|
297
|
+
const attemptId = (await cookies()).get('signup_attempt')?.value ?? ''
|
|
298
|
+
const clientIp = (await headers()).get('x-forwarded-for')?.split(',').at(-1)?.trim() ?? ''
|
|
299
|
+
|
|
300
|
+
const decision = await decide(requestId, `signup:${attemptId}`, clientIp)
|
|
301
|
+
if (decision === 'refuse') return { error: 'Please try again.' }
|
|
302
|
+
if (decision === 'challenge') return { challenge: true }
|
|
303
|
+
// allow, or queue for review
|
|
151
304
|
}
|
|
152
305
|
```
|
|
153
306
|
|
|
307
|
+
## Decide on your backend
|
|
308
|
+
|
|
309
|
+
The `requestId` in the form is untrusted form input until your backend has
|
|
310
|
+
verified it: whoever submits the form chooses its value. Read the event with
|
|
311
|
+
the secret key and run the checks described in
|
|
312
|
+
[server-side verification](https://docs.fingerly.io/docs/server-side-verification):
|
|
313
|
+
|
|
314
|
+
```ts
|
|
315
|
+
// lib/fingerly.ts (server only)
|
|
316
|
+
import { BlockList } from 'node:net'
|
|
317
|
+
import { Fingerly, FingerlyAPIError } from '@fingerly/node'
|
|
318
|
+
|
|
319
|
+
const fingerly = new Fingerly({ secretKey: process.env.FINGERLY_SECRET_KEY })
|
|
320
|
+
const MAX_AGE_MS = 2 * 60 * 1000
|
|
321
|
+
|
|
322
|
+
// expectedTag comes from your server session, never from the form. clientIp is
|
|
323
|
+
// the address of this form post, as your platform resolves it.
|
|
324
|
+
export async function decide(requestId: string, expectedTag: string, clientIp: string) {
|
|
325
|
+
let event
|
|
326
|
+
try {
|
|
327
|
+
event = await fingerly.events.get(requestId) // 1. it exists
|
|
328
|
+
} catch (error) {
|
|
329
|
+
if (error instanceof FingerlyAPIError && error.isPending) return 'retry'
|
|
330
|
+
if (error instanceof FingerlyAPIError && error.code === 'event_not_found') return 'refuse'
|
|
331
|
+
throw error
|
|
332
|
+
}
|
|
333
|
+
if (event.tag !== expectedTag) return 'refuse' // 2. this action
|
|
334
|
+
if (Date.now() - Date.parse(event.occurred_at) > MAX_AGE_MS) return 'refuse' // 3. recent
|
|
335
|
+
if (!event.identifiable || event.suspect_score === null) return 'refuse' // 4. identifiable and scored
|
|
336
|
+
if (event.suspect_level === 'high') return 'review' // 5. your policy
|
|
337
|
+
// 6. another network than this post: step up (for example a second factor)
|
|
338
|
+
if (!event.ip_network || !inNetwork(clientIp, event.ip_network)) return 'challenge'
|
|
339
|
+
if (event.suspect_level === 'medium') return 'challenge'
|
|
340
|
+
return 'allow'
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
// ip_network is the /24 (IPv4) or /40 (IPv6) the identification came from;
|
|
344
|
+
// the API never returns the address itself.
|
|
345
|
+
function inNetwork(ip: string, cidr: string): boolean {
|
|
346
|
+
const [base = '', bits = '0'] = cidr.split('/')
|
|
347
|
+
const type = base.includes(':') ? 'ipv6' : 'ipv4'
|
|
348
|
+
const list = new BlockList()
|
|
349
|
+
list.addSubnet(base, Number(bits), type)
|
|
350
|
+
return list.check(ip, type)
|
|
351
|
+
}
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
One event can back more than one decision inside the recency window. For a
|
|
355
|
+
flow that must be single use, record the `requestId` with the outcome and refuse
|
|
356
|
+
one you have already seen.
|
|
357
|
+
|
|
154
358
|
`<FingerlyRequestId />` identifies on mount and renders a hidden field. It is in
|
|
155
359
|
the server-rendered HTML **empty** rather than absent, which is deliberate: a
|
|
156
360
|
form submitted before the SDK finished, or with JavaScript disabled, is a
|
|
157
361
|
normal event, and the server can tell it apart from a form that never carried a
|
|
158
|
-
field at all.
|
|
362
|
+
field at all. Turn `immediate` off in a form that identifies at submit time
|
|
363
|
+
instead.
|
|
159
364
|
|
|
160
365
|
`readRequestId()` returns `null` for all of those cases rather than throwing:
|
|
161
366
|
what to do about an unidentified submission is a policy your server owns. It
|
|
162
|
-
also refuses anything that is not a short opaque token
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
storing what the visitor
|
|
367
|
+
also refuses anything that is not a short opaque token (at most 128 characters
|
|
368
|
+
of letters, digits, `_` and `-`): the field arrives from the page, which means
|
|
369
|
+
it arrives from whoever is driving the browser, and a server that joins or logs
|
|
370
|
+
it unchecked is one hand-written `<input>` away from storing what the visitor
|
|
371
|
+
typed.
|
|
166
372
|
|
|
167
373
|
Both halves agree on the field name through one exported constant,
|
|
168
|
-
`REQUEST_ID_FIELD
|
|
169
|
-
`readRequestId()` if you need a
|
|
374
|
+
`REQUEST_ID_FIELD` (`fingerly_request_id`). Pass `name` to
|
|
375
|
+
`<FingerlyRequestId />` and the same `name` to `readRequestId()` if you need a
|
|
376
|
+
different one.
|
|
170
377
|
|
|
171
|
-
## The two entries
|
|
378
|
+
## The two entries
|
|
172
379
|
|
|
173
380
|
| Import | Runs | Contains |
|
|
174
381
|
| --- | --- | --- |
|
|
175
382
|
| `@fingerly/next` | the browser | provider, field, hooks (a `'use client'` module) |
|
|
176
|
-
| `@fingerly/next/server` | the server | `readRequestId`, `REQUEST_ID_FIELD` (no React) |
|
|
383
|
+
| `@fingerly/next/server` | the server | `readRequestId`, `REQUEST_ID_FIELD`, `createFingerlyProxy` (no React) |
|
|
177
384
|
|
|
178
385
|
A Server Action that imported `readRequestId` from the main entry would get a
|
|
179
386
|
client reference rather than a function: the import succeeds and the call fails
|
|
180
387
|
at runtime, which is the worst way to learn about a boundary. Hence the split.
|
|
181
388
|
|
|
182
|
-
##
|
|
389
|
+
## Errors
|
|
183
390
|
|
|
184
|
-
|
|
185
|
-
|
|
391
|
+
The error types are `@fingerly/react`'s (`ConsentError`, `TransportError`,
|
|
392
|
+
`FingerlyServerError`), documented in the
|
|
393
|
+
[React binding's README](https://github.com/fingerly-io/sdks/tree/main/client/web/react#errors).
|
|
394
|
+
Two things are particular to this package:
|
|
186
395
|
|
|
187
|
-
|
|
396
|
+
- A missing key is reported once on the console and the page keeps rendering;
|
|
397
|
+
`identify()` then fails with the SDK's own message about a missing key.
|
|
398
|
+
- A `NEXT_PUBLIC_FINGERLY_ENDPOINTS` that is not a non-empty JSON array of
|
|
399
|
+
strings is reported once and ignored, rather than thrown from a render.
|
|
400
|
+
|
|
401
|
+
## What this does not do
|
|
402
|
+
|
|
403
|
+
**It does not proxy the API itself.** See [First-party endpoints](#first-party-endpoints):
|
|
404
|
+
the proxy comes from `@fingerly/node`.
|
|
405
|
+
|
|
406
|
+
**It does not read events back.** `identify()` resolves in one round trip with
|
|
407
|
+
the server's client-facing answer (`visitorId`, `identifiable`, and
|
|
408
|
+
`suspectScore` and `suspectLevel` unless the key hides them), so there is
|
|
409
|
+
nothing to fetch afterwards in the page. Reading full stored events and their
|
|
410
|
+
risk signals on your backend is `@fingerly/node`'s job (see
|
|
411
|
+
[server-side verification](https://docs.fingerly.io/docs/server-side-verification)).
|
|
412
|
+
|
|
413
|
+
## More
|
|
414
|
+
|
|
415
|
+
<details>
|
|
416
|
+
<summary>Running the demo</summary>
|
|
417
|
+
|
|
418
|
+
`demo/` (in the
|
|
419
|
+
[repository](https://github.com/fingerly-io/sdks/tree/main/client/web/next)) is
|
|
420
|
+
a real Next application: a Server Component layout, a client page, and a Server
|
|
421
|
+
Action reading the field back:
|
|
422
|
+
|
|
423
|
+
```sh
|
|
188
424
|
pnpm --filter @fingerly/next demo # http://localhost:4178
|
|
189
425
|
```
|
|
190
426
|
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
read.
|
|
427
|
+
Put `FINGERLY_API_KEY` and `FINGERLY_ENDPOINT` in `demo/.env.local` (gitignored),
|
|
428
|
+
with a key whose allowed origins include the port you are running it on. Then
|
|
429
|
+
the identification produces a real `requestId`, the hidden field carries it, and
|
|
430
|
+
the action prints the one it read.
|
|
196
431
|
|
|
197
|
-
|
|
198
|
-
card change.
|
|
432
|
+
</details>
|
|
199
433
|
|
|
200
|
-
##
|
|
434
|
+
## TypeScript
|
|
201
435
|
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
436
|
+
Types ship with the package, for both entries. The main entry exports
|
|
437
|
+
`FingerlyNextProviderProps`, `FingerlyRequestIdProps`, `FingerlyReactOptions`,
|
|
438
|
+
`FingerlyState`, `FingerlyStore`, `UseIdentifyOptions`, `UseIdentifyReturn`,
|
|
439
|
+
`IdentifyAnswer`, `IdentifyOptions`, `IdentifyResult`, `IncognitoDetection`,
|
|
440
|
+
`ConsentState`, `SuspectLevel`, `SignalReport` and `Confidence`, and the values
|
|
441
|
+
`FingerlyProvider`, `FingerlyRequestId`, `useIdentify`, `useFingerly`,
|
|
442
|
+
`createFingerlyStore`, `ConsentError`, `TransportError`, `FingerlyServerError`
|
|
443
|
+
and `REQUEST_ID_FIELD`. `@fingerly/next/server` exports `readRequestId`,
|
|
444
|
+
`REQUEST_ID_FIELD`, `createFingerlyProxy` and `FingerlyProxyOptions`. Both
|
|
445
|
+
entries ship ES module and CommonJS builds.
|
|
208
446
|
|
|
209
|
-
|
|
210
|
-
// app/k7x2qm4a/route.ts
|
|
211
|
-
import { Fingerly } from '@fingerly/node'
|
|
447
|
+
## Requirements
|
|
212
448
|
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
449
|
+
Next **15 or newer** and React **19** (App Router or Pages Router). Tested
|
|
450
|
+
against Next 16. The browser SDK it wraps needs ES2020 with `fetch` and
|
|
451
|
+
`AbortController`: every current version of Chrome, Edge, Firefox and Safari.
|
|
452
|
+
The `@fingerly/next/server` entry depends on `@fingerly/node`, which is
|
|
453
|
+
installed with it.
|
|
216
454
|
|
|
217
|
-
|
|
218
|
-
proxy ??= Fingerly.createProxy({
|
|
219
|
-
proxyKey: process.env.FINGERLY_PROXY_KEY!,
|
|
220
|
-
// The last X-Forwarded-For entry is the address your own server or load
|
|
221
|
-
// balancer saw. Read a CDN's client-IP header instead only when traffic
|
|
222
|
-
// can reach this app through that CDN alone.
|
|
223
|
-
clientIp: (req) => req.headers.get('x-forwarded-for')?.split(',').at(-1)?.trim() ?? '',
|
|
224
|
-
})
|
|
225
|
-
return proxy(request)
|
|
226
|
-
}
|
|
227
|
-
```
|
|
455
|
+
## Documentation
|
|
228
456
|
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
457
|
+
The Next.js guide is at
|
|
458
|
+
[docs.fingerly.io](https://docs.fingerly.io/docs/sdks/nextjs). The React binding
|
|
459
|
+
underneath is [`@fingerly/react`](https://www.npmjs.com/package/@fingerly/react).
|
|
460
|
+
|
|
461
|
+
## Help
|
|
462
|
+
|
|
463
|
+
Open an issue on [fingerly-io/sdks](https://github.com/fingerly-io/sdks/issues),
|
|
464
|
+
or write to [support@fingerly.io](mailto:support@fingerly.io). Security issues:
|
|
465
|
+
[security@fingerly.io](mailto:security@fingerly.io).
|
|
466
|
+
|
|
467
|
+
## Licence
|
|
232
468
|
|
|
233
|
-
|
|
234
|
-
with the server's answer (`visitorId`, and `suspectScore` and `suspectLevel`
|
|
235
|
-
unless the key hides them), so there is nothing to fetch afterwards. Reading stored
|
|
236
|
-
events for reporting is `@fingerly/node`'s job.
|
|
469
|
+
[Apache-2.0](https://github.com/fingerly-io/sdks/blob/main/client/web/next/LICENSE). Fingerly is a product of Badele LLC.
|
package/dist/index.cjs
CHANGED
|
@@ -79,7 +79,7 @@ function FingerlyProvider(props) {
|
|
|
79
79
|
...props.apiVersion === void 0 ? {} : { apiVersion: props.apiVersion },
|
|
80
80
|
...endpoints === void 0 ? {} : { endpoints },
|
|
81
81
|
...props.fallbackToDefaultEndpoint === void 0 ? {} : { fallbackToDefaultEndpoint: props.fallbackToDefaultEndpoint },
|
|
82
|
-
...props.
|
|
82
|
+
...props.incognitoDetection === void 0 ? {} : { incognitoDetection: props.incognitoDetection },
|
|
83
83
|
...props.consent === void 0 ? {} : { consent: props.consent },
|
|
84
84
|
children: props.children
|
|
85
85
|
}
|
|
@@ -94,8 +94,8 @@ var REQUEST_ID_FIELD = "fingerly_request_id";
|
|
|
94
94
|
|
|
95
95
|
// src/field.tsx
|
|
96
96
|
var import_jsx_runtime2 = require("react/jsx-runtime");
|
|
97
|
-
function FingerlyRequestId({ name, immediate = true } = {}) {
|
|
98
|
-
const { requestId } = (0, import_react2.useIdentify)({ immediate });
|
|
97
|
+
function FingerlyRequestId({ name, immediate = true, tag } = {}) {
|
|
98
|
+
const { requestId } = (0, import_react2.useIdentify)({ immediate, ...tag === void 0 ? {} : { tag } });
|
|
99
99
|
return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
|
|
100
100
|
"input",
|
|
101
101
|
{
|
package/dist/index.d.cts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { ConsentState } from '@fingerly/react';
|
|
2
|
-
export { Confidence, ConsentError, ConsentState, FingerlyReactOptions, FingerlyServerError, FingerlyState, FingerlyStore, IdentifyResult, SignalReport, TransportError, UseIdentifyOptions, UseIdentifyReturn, createFingerlyStore, useFingerly, useIdentify } from '@fingerly/react';
|
|
1
|
+
import { IncognitoDetection, ConsentState } from '@fingerly/react';
|
|
2
|
+
export { Confidence, ConsentError, ConsentState, FingerlyReactOptions, FingerlyServerError, FingerlyState, FingerlyStore, IdentifyAnswer, IdentifyOptions, IdentifyResult, IncognitoDetection, SignalReport, SuspectLevel, TransportError, UseIdentifyOptions, UseIdentifyReturn, createFingerlyStore, useFingerly, useIdentify } from '@fingerly/react';
|
|
3
3
|
import { ReactNode } from 'react';
|
|
4
4
|
export { R as REQUEST_ID_FIELD } from './field-name-CAkWsUa5.cjs';
|
|
5
5
|
|
|
@@ -16,8 +16,8 @@ interface FingerlyNextProviderProps {
|
|
|
16
16
|
endpoints?: string | readonly string[];
|
|
17
17
|
/** Opt into the Fingerly API after custom endpoints fail. */
|
|
18
18
|
fallbackToDefaultEndpoint?: boolean;
|
|
19
|
-
/**
|
|
20
|
-
|
|
19
|
+
/** Opt-in extended incognito probe control (`'standard'` or `'extended'`). */
|
|
20
|
+
incognitoDetection?: IncognitoDetection;
|
|
21
21
|
/**
|
|
22
22
|
* Whether the visitor has agreed to be identified. Defaults to `pending`.
|
|
23
23
|
*
|
|
@@ -44,6 +44,14 @@ interface FingerlyRequestIdProps {
|
|
|
44
44
|
* that identifies at submit time instead.
|
|
45
45
|
*/
|
|
46
46
|
immediate?: boolean;
|
|
47
|
+
/**
|
|
48
|
+
* Correlation tag echoed on the event, such as `signup:${attemptId}` where
|
|
49
|
+
* `attemptId` is a random value your server issued with this form. The
|
|
50
|
+
* backend compares the event's `tag` with the one it expects, so a
|
|
51
|
+
* `requestId` from another page or session is refused. Never put a
|
|
52
|
+
* personal identifier in a tag.
|
|
53
|
+
*/
|
|
54
|
+
tag?: string;
|
|
47
55
|
}
|
|
48
56
|
/**
|
|
49
57
|
* A hidden input carrying this page's `requestId`.
|
|
@@ -63,6 +71,6 @@ interface FingerlyRequestIdProps {
|
|
|
63
71
|
*
|
|
64
72
|
* Read it back with `readRequestId(formData)` from `@fingerly/next/server`.
|
|
65
73
|
*/
|
|
66
|
-
declare function FingerlyRequestId({ name, immediate }?: FingerlyRequestIdProps): ReactNode;
|
|
74
|
+
declare function FingerlyRequestId({ name, immediate, tag }?: FingerlyRequestIdProps): ReactNode;
|
|
67
75
|
|
|
68
76
|
export { type FingerlyNextProviderProps, FingerlyProvider, FingerlyRequestId, type FingerlyRequestIdProps };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { ConsentState } from '@fingerly/react';
|
|
2
|
-
export { Confidence, ConsentError, ConsentState, FingerlyReactOptions, FingerlyServerError, FingerlyState, FingerlyStore, IdentifyResult, SignalReport, TransportError, UseIdentifyOptions, UseIdentifyReturn, createFingerlyStore, useFingerly, useIdentify } from '@fingerly/react';
|
|
1
|
+
import { IncognitoDetection, ConsentState } from '@fingerly/react';
|
|
2
|
+
export { Confidence, ConsentError, ConsentState, FingerlyReactOptions, FingerlyServerError, FingerlyState, FingerlyStore, IdentifyAnswer, IdentifyOptions, IdentifyResult, IncognitoDetection, SignalReport, SuspectLevel, TransportError, UseIdentifyOptions, UseIdentifyReturn, createFingerlyStore, useFingerly, useIdentify } from '@fingerly/react';
|
|
3
3
|
import { ReactNode } from 'react';
|
|
4
4
|
export { R as REQUEST_ID_FIELD } from './field-name-CAkWsUa5.js';
|
|
5
5
|
|
|
@@ -16,8 +16,8 @@ interface FingerlyNextProviderProps {
|
|
|
16
16
|
endpoints?: string | readonly string[];
|
|
17
17
|
/** Opt into the Fingerly API after custom endpoints fail. */
|
|
18
18
|
fallbackToDefaultEndpoint?: boolean;
|
|
19
|
-
/**
|
|
20
|
-
|
|
19
|
+
/** Opt-in extended incognito probe control (`'standard'` or `'extended'`). */
|
|
20
|
+
incognitoDetection?: IncognitoDetection;
|
|
21
21
|
/**
|
|
22
22
|
* Whether the visitor has agreed to be identified. Defaults to `pending`.
|
|
23
23
|
*
|
|
@@ -44,6 +44,14 @@ interface FingerlyRequestIdProps {
|
|
|
44
44
|
* that identifies at submit time instead.
|
|
45
45
|
*/
|
|
46
46
|
immediate?: boolean;
|
|
47
|
+
/**
|
|
48
|
+
* Correlation tag echoed on the event, such as `signup:${attemptId}` where
|
|
49
|
+
* `attemptId` is a random value your server issued with this form. The
|
|
50
|
+
* backend compares the event's `tag` with the one it expects, so a
|
|
51
|
+
* `requestId` from another page or session is refused. Never put a
|
|
52
|
+
* personal identifier in a tag.
|
|
53
|
+
*/
|
|
54
|
+
tag?: string;
|
|
47
55
|
}
|
|
48
56
|
/**
|
|
49
57
|
* A hidden input carrying this page's `requestId`.
|
|
@@ -63,6 +71,6 @@ interface FingerlyRequestIdProps {
|
|
|
63
71
|
*
|
|
64
72
|
* Read it back with `readRequestId(formData)` from `@fingerly/next/server`.
|
|
65
73
|
*/
|
|
66
|
-
declare function FingerlyRequestId({ name, immediate }?: FingerlyRequestIdProps): ReactNode;
|
|
74
|
+
declare function FingerlyRequestId({ name, immediate, tag }?: FingerlyRequestIdProps): ReactNode;
|
|
67
75
|
|
|
68
76
|
export { type FingerlyNextProviderProps, FingerlyProvider, FingerlyRequestId, type FingerlyRequestIdProps };
|
package/dist/index.js
CHANGED
|
@@ -4,7 +4,9 @@ import {
|
|
|
4
4
|
} from "./chunk-2RV4QBLR.js";
|
|
5
5
|
|
|
6
6
|
// src/provider.tsx
|
|
7
|
-
import {
|
|
7
|
+
import {
|
|
8
|
+
FingerlyProvider as ReactFingerlyProvider
|
|
9
|
+
} from "@fingerly/react";
|
|
8
10
|
import { jsx } from "react/jsx-runtime";
|
|
9
11
|
function fromEnvironment() {
|
|
10
12
|
const apiKey = typeof process === "undefined" ? void 0 : process.env.NEXT_PUBLIC_FINGERLY_API_KEY;
|
|
@@ -49,7 +51,7 @@ function FingerlyProvider(props) {
|
|
|
49
51
|
...props.apiVersion === void 0 ? {} : { apiVersion: props.apiVersion },
|
|
50
52
|
...endpoints === void 0 ? {} : { endpoints },
|
|
51
53
|
...props.fallbackToDefaultEndpoint === void 0 ? {} : { fallbackToDefaultEndpoint: props.fallbackToDefaultEndpoint },
|
|
52
|
-
...props.
|
|
54
|
+
...props.incognitoDetection === void 0 ? {} : { incognitoDetection: props.incognitoDetection },
|
|
53
55
|
...props.consent === void 0 ? {} : { consent: props.consent },
|
|
54
56
|
children: props.children
|
|
55
57
|
}
|
|
@@ -59,8 +61,8 @@ function FingerlyProvider(props) {
|
|
|
59
61
|
// src/field.tsx
|
|
60
62
|
import { useIdentify } from "@fingerly/react";
|
|
61
63
|
import { jsx as jsx2 } from "react/jsx-runtime";
|
|
62
|
-
function FingerlyRequestId({ name, immediate = true } = {}) {
|
|
63
|
-
const { requestId } = useIdentify({ immediate });
|
|
64
|
+
function FingerlyRequestId({ name, immediate = true, tag } = {}) {
|
|
65
|
+
const { requestId } = useIdentify({ immediate, ...tag === void 0 ? {} : { tag } });
|
|
64
66
|
return /* @__PURE__ */ jsx2(
|
|
65
67
|
"input",
|
|
66
68
|
{
|
package/dist/server.d.cts
CHANGED
|
@@ -25,6 +25,13 @@ export { ProxyOptions as FingerlyProxyOptions, createProxy as createFingerlyProx
|
|
|
25
25
|
* }
|
|
26
26
|
* ```
|
|
27
27
|
*
|
|
28
|
+
* The value is still untrusted after this: it only has the right shape. Read
|
|
29
|
+
* the event with `fingerly.events.get(requestId)` and a secret key, and check
|
|
30
|
+
* that it exists, that its `tag` is the one this action expects, that it is
|
|
31
|
+
* recent, and that its `ip_network` contains the address of this request,
|
|
32
|
+
* before acting on it. See
|
|
33
|
+
* https://docs.fingerly.io/docs/server-side-verification.
|
|
34
|
+
*
|
|
28
35
|
* Returns null rather than throwing when the field is missing, empty or
|
|
29
36
|
* malformed, because all three mean the same thing to the caller: this
|
|
30
37
|
* submission has no identification attached. A form submitted before the SDK
|
package/dist/server.d.ts
CHANGED
|
@@ -25,6 +25,13 @@ export { ProxyOptions as FingerlyProxyOptions, createProxy as createFingerlyProx
|
|
|
25
25
|
* }
|
|
26
26
|
* ```
|
|
27
27
|
*
|
|
28
|
+
* The value is still untrusted after this: it only has the right shape. Read
|
|
29
|
+
* the event with `fingerly.events.get(requestId)` and a secret key, and check
|
|
30
|
+
* that it exists, that its `tag` is the one this action expects, that it is
|
|
31
|
+
* recent, and that its `ip_network` contains the address of this request,
|
|
32
|
+
* before acting on it. See
|
|
33
|
+
* https://docs.fingerly.io/docs/server-side-verification.
|
|
34
|
+
*
|
|
28
35
|
* Returns null rather than throwing when the field is missing, empty or
|
|
29
36
|
* malformed, because all three mean the same thing to the caller: this
|
|
30
37
|
* submission has no identification attached. A form submitted before the SDK
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fingerly/next",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"publishConfig": {
|
|
5
5
|
"access": "public"
|
|
6
6
|
},
|
|
@@ -32,8 +32,8 @@
|
|
|
32
32
|
],
|
|
33
33
|
"sideEffects": false,
|
|
34
34
|
"dependencies": {
|
|
35
|
-
"@fingerly/node": "0.
|
|
36
|
-
"@fingerly/react": "0.
|
|
35
|
+
"@fingerly/node": "0.3.0",
|
|
36
|
+
"@fingerly/react": "0.3.0"
|
|
37
37
|
},
|
|
38
38
|
"peerDependencies": {
|
|
39
39
|
"next": ">=15",
|
|
@@ -49,7 +49,7 @@
|
|
|
49
49
|
"tsup": "^8.3.5",
|
|
50
50
|
"typescript": "^5.7.2",
|
|
51
51
|
"vitest": "^2.1.8",
|
|
52
|
-
"@fingerly/web-js": "0.
|
|
52
|
+
"@fingerly/web-js": "0.3.0"
|
|
53
53
|
},
|
|
54
54
|
"scripts": {
|
|
55
55
|
"build": "tsup",
|