@useauthio/react 0.2.4 → 0.3.1
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/CHANGELOG.md +79 -0
- package/README.md +88 -19
- package/dist/index.cjs +496 -63
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +358 -27
- package/dist/index.d.ts +358 -27
- package/dist/index.js +485 -65
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
- package/src/PasskeyManager.tsx +4 -3
- package/src/activity.ts +95 -0
- package/src/device-signals.ts +86 -0
- package/src/errors.ts +239 -17
- package/src/fetch.ts +23 -12
- package/src/index.ts +37 -3
- package/src/lobby-context.ts +16 -0
- package/src/locate.ts +42 -0
- package/src/passkeys.ts +18 -8
- package/src/provider.tsx +111 -15
- package/src/refresh.ts +41 -0
- package/src/sign-in.ts +263 -29
- package/src/telemetry.ts +11 -0
- package/src/types.ts +71 -0
- package/src/usePasskeys.ts +13 -4
- package/src/version.ts +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,85 @@ All notable changes to `@useauthio/react` are documented here. This
|
|
|
4
4
|
project adheres to [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
|
|
5
5
|
and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
6
|
|
|
7
|
+
## [0.3.1] — 2026-11-21
|
|
8
|
+
|
|
9
|
+
### Fixed
|
|
10
|
+
- **`signInWithPasskey` no longer crashes on a risk step-up.** When
|
|
11
|
+
auth-core's risk engine answered `decision: "step_up"` (HTTP 200, no
|
|
12
|
+
`user`), the helper read `verifyRes.user.id` and threw
|
|
13
|
+
`Cannot read properties of undefined (reading 'id')`. Sign-in helpers
|
|
14
|
+
now never assume `user` or tokens are present.
|
|
15
|
+
|
|
16
|
+
### Added
|
|
17
|
+
- `AuthioStepUpRequiredError` (code `step_up_required`, thrown by
|
|
18
|
+
`signInWithPasskey` and `verifyEmailOtp`) with `stepUpUrl`,
|
|
19
|
+
`challengeId`, `requiredMethod`, `reasons` and `enrollmentRequired`.
|
|
20
|
+
`stepUpUrl` is the hosted step-up page from auth-core's new
|
|
21
|
+
`step_up_url` field. `isStepUpRequired(err)` type guard.
|
|
22
|
+
- `AuthioSignInDeniedError` (code `sign_in_denied`) for risk or policy
|
|
23
|
+
denies (403 `decision: "block"`), carrying the server's message plus
|
|
24
|
+
`denyCode` and `reasons`.
|
|
25
|
+
- `invalid_response` when a sign-in call returns 200 without a session.
|
|
26
|
+
- `AUTHIO_MESSAGES`, the SDK's user-facing copy.
|
|
27
|
+
|
|
28
|
+
### Changed
|
|
29
|
+
- Every error message the SDK writes itself is now plain English and
|
|
30
|
+
actionable. Raw browser or network text ("Failed to fetch",
|
|
31
|
+
WebAuthn's "The operation either timed out or was not allowed…") moves
|
|
32
|
+
to `err.cause`. Server-sent messages are passed through unchanged.
|
|
33
|
+
- The SDK's own request timeout now reports code `timeout` (it used to
|
|
34
|
+
report `aborted`).
|
|
35
|
+
- Risk denies used to surface auth-core's code (for example
|
|
36
|
+
`blocked_by_risk_policy`). They now use `sign_in_denied`, and the
|
|
37
|
+
original code is on `err.denyCode`.
|
|
38
|
+
- `usePasskeys` actions throw `AuthioError` `not_signed_in`, not a bare
|
|
39
|
+
`Error`. Adding a passkey that already exists reports
|
|
40
|
+
`webauthn_already_registered`.
|
|
41
|
+
|
|
42
|
+
## [0.3.0] — 2026-09-03
|
|
43
|
+
|
|
44
|
+
### Added
|
|
45
|
+
- **Session policy on the context.** `useAuthio().sessionPolicy` exposes the
|
|
46
|
+
effective session-lifecycle limits auth-core now reports in the
|
|
47
|
+
`session_policy` field of every envelope (`idleTimeoutMin`,
|
|
48
|
+
`absoluteMaxMin`, `accessTokenTtlMin`; minutes, `0` = no limit). `null` on
|
|
49
|
+
auth-core versions that predate the field. `signInWithPasskey` and
|
|
50
|
+
`verifyEmailOtp` results carry the same value, and `handleSignInResult`
|
|
51
|
+
accepts it.
|
|
52
|
+
- **Inactivity-aware silent refresh.** When the effective policy has an
|
|
53
|
+
inactivity timeout and the user has not interacted with the page since the
|
|
54
|
+
last refresh, the scheduled refresh is held until the next interaction
|
|
55
|
+
(pointer, key, touch, scroll, focus, or tab returning to the foreground)
|
|
56
|
+
instead of keeping an idle session alive. Projects without an inactivity
|
|
57
|
+
policy — and any auth-core that does not send `session_policy` — keep the
|
|
58
|
+
previous always-refresh behaviour, so existing apps are unaffected until
|
|
59
|
+
their project opts into an inactivity limit.
|
|
60
|
+
- New provider prop `idleRefresh: "defer" | "always"` (default `"defer"`) as
|
|
61
|
+
an escape hatch for apps whose background work needs a warm token while
|
|
62
|
+
the user is away.
|
|
63
|
+
- Telemetry events `refresh_deferred` (`reason: "hidden" | "idle"`) and
|
|
64
|
+
`refresh_resumed`.
|
|
65
|
+
- Exported `ActivityTracker`, `coerceSessionPolicy`, and the
|
|
66
|
+
`SessionPolicy` / `RawSessionPolicy` / `AuthioIdleRefreshMode` /
|
|
67
|
+
`RefreshDeferReason` types.
|
|
68
|
+
|
|
69
|
+
## [0.2.5] — 2026-07-01
|
|
70
|
+
|
|
71
|
+
### Added
|
|
72
|
+
- **Email OTP sign-in.** `sendEmailOtp({ email, redirectUri?, next?, organizationId? })`
|
|
73
|
+
and `verifyEmailOtp({ email, code, next?, organizationId?, clientLocation?, deviceSignals? })`
|
|
74
|
+
helpers for auth-core's `/v1/auth/email-otp/send` + `/verify`, mirroring the
|
|
75
|
+
hosted Lobby's body shapes. `verifyEmailOtp` throws a typed
|
|
76
|
+
`step_up_required` `AuthioError` when the risk engine withholds the session.
|
|
77
|
+
- **`signInWithPasskey` org/next forwarding.** Optional `next` and
|
|
78
|
+
`organizationId` are now included in the passkey login verify body when
|
|
79
|
+
provided. Older auth-core deployments ignore the fields; client-side token
|
|
80
|
+
handling is unchanged.
|
|
81
|
+
|
|
82
|
+
### Fixed
|
|
83
|
+
- `SDK_VERSION` (and the `X-Authio-SDK` header) had drifted from
|
|
84
|
+
`package.json` — re-synced.
|
|
85
|
+
|
|
7
86
|
## [0.2.4] — 2026-06-19
|
|
8
87
|
|
|
9
88
|
### Added
|
package/README.md
CHANGED
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
> https://authio.com/products/lobby.
|
|
13
13
|
|
|
14
14
|
React SDK for Authio — hooks, gates, and sign-in helpers for **pure
|
|
15
|
-
SPAs** that talk directly to
|
|
15
|
+
SPAs** that talk directly to the identity API via CORS. If you have a
|
|
16
16
|
Next.js or other BFF, reach for [`@useauthio/nextjs`](https://github.com/authio-com/authio_nextjs)
|
|
17
17
|
instead.
|
|
18
18
|
|
|
@@ -129,7 +129,7 @@ function MagicLinkForm() {
|
|
|
129
129
|
That's it. The provider runs a silent `POST /v1/auth/refresh` against
|
|
130
130
|
your BFF cookie at mount, schedules a renewal one minute before the
|
|
131
131
|
access JWT expires, and verifies every received token against the
|
|
132
|
-
|
|
132
|
+
identity API JWKS before trusting it.
|
|
133
133
|
|
|
134
134
|
A complete runnable example lives in [`examples/vite-react/`](./examples/vite-react/).
|
|
135
135
|
|
|
@@ -162,10 +162,11 @@ that CNAME at runtime — it only affects where end users sign in when you overr
|
|
|
162
162
|
|
|
163
163
|
| Prop | Type | Default | Description |
|
|
164
164
|
|------|------|---------|-------------|
|
|
165
|
-
| `apiUrl` | `string` (required) | — |
|
|
165
|
+
| `apiUrl` | `string` (required) | — | Identity API base URL, e.g. `"https://identity.authio.com"` (legacy alias `auth-api.authio.com`). |
|
|
166
166
|
| `projectId` | `string` (required) | — | Environment ID (`proj_…`; API field `project_id`). Sent as `X-Authio-Project` on every call. |
|
|
167
167
|
| `storage` | `"memory" \| "localStorage" \| "sessionStorage" \| "none"` | `"memory"` | Access-token storage backend. **Refresh tokens are never JS-accessible** regardless of this setting. |
|
|
168
168
|
| `refreshLeadSeconds` | `number` | `60` | How many seconds before `exp` to schedule the silent refresh. |
|
|
169
|
+
| `idleRefresh` | `"defer" \| "always"` | `"defer"` | Under a project/org **inactivity timeout** (`sessionPolicy.idleTimeoutMin > 0`), `"defer"` holds the timer-driven refresh until the user next interacts, so an idle tab doesn't keep the session alive. Projects without an inactivity policy are unaffected. `"always"` restores unconditional timer refresh. |
|
|
169
170
|
| `onTelemetryEvent` | `(event: AuthioTelemetryEvent) => void` | — | Sink for SDK telemetry (refresh outcomes, sign-in starts/completes, token verification). No phone-home by default. |
|
|
170
171
|
| `fetch` | `typeof fetch` | `globalThis.fetch` | DI for tests / custom transports. |
|
|
171
172
|
| `signInUrl` | `string` | `https://lobby.authio.com/` | Lobby (hosted UI) sign-in URL. Set to your branded auth host (e.g. `https://auth.acme.com/`) when using a custom domain — see [Custom auth domains](#custom-auth-domains) below. |
|
|
@@ -181,6 +182,7 @@ that CNAME at runtime — it only affects where end users sign in when you overr
|
|
|
181
182
|
user: AuthioUser | null;
|
|
182
183
|
status: "loading" | "authenticated" | "unauthenticated";
|
|
183
184
|
accessToken: string | null;
|
|
185
|
+
sessionPolicy: SessionPolicy | null; // { idleTimeoutMin, absoluteMaxMin, accessTokenTtlMin } in minutes, 0 = no limit
|
|
184
186
|
getAccessToken: () => Promise<string | null>;
|
|
185
187
|
signIn: (opts?: { returnTo?: string }) => void;
|
|
186
188
|
signOut: () => Promise<void>;
|
|
@@ -188,11 +190,16 @@ that CNAME at runtime — it only affects where end users sign in when you overr
|
|
|
188
190
|
}
|
|
189
191
|
```
|
|
190
192
|
|
|
193
|
+
- `sessionPolicy` mirrors the `session_policy` object auth-core returns on
|
|
194
|
+
every session envelope — the effective inactivity / maximum-session /
|
|
195
|
+
access-token limits for the current project or organization. `null`
|
|
196
|
+
until the first successful refresh or sign-in, and on auth-core versions
|
|
197
|
+
that predate the field.
|
|
191
198
|
- `getAccessToken()` returns the current token if it's more than 10s
|
|
192
199
|
from `exp`, otherwise transparently triggers a refresh and returns
|
|
193
200
|
the new value (or `null` on failure). Use it as your `Authorization`
|
|
194
201
|
source for outbound API calls.
|
|
195
|
-
- `signIn()` navigates the tab to Lobby (`signInUrl`). When
|
|
202
|
+
- `signIn()` navigates the tab to Lobby (`signInUrl`). When identity API
|
|
196
203
|
supports it, the SDK mints a short-lived `ctx` token so
|
|
197
204
|
`project_id` and `redirect_uri` are not exposed in the URL; it falls
|
|
198
205
|
back to legacy `?project_id=…&redirect_uri=…` query params otherwise.
|
|
@@ -239,10 +246,13 @@ Runs the full WebAuthn assertion ceremony against
|
|
|
239
246
|
`/v1/auth/passkey/login/options` + `/v1/auth/passkey/login/verify`.
|
|
240
247
|
Returns `{ accessToken, refreshToken?, user }`. Throws `AuthioError`
|
|
241
248
|
with codes `not_in_browser`, `webauthn_unsupported`,
|
|
242
|
-
`webauthn_cancelled`,
|
|
249
|
+
`webauthn_cancelled`, `step_up_required`, `sign_in_denied`,
|
|
250
|
+
`invalid_response`, or any identity API error code on a step failure.
|
|
251
|
+
`verifyEmailOtp` throws the same risk-engine codes. See
|
|
252
|
+
[Handling risk checks](#handling-risk-checks-step-up-and-deny).
|
|
243
253
|
|
|
244
254
|
The returned `refreshToken` is included for completeness but the SDK
|
|
245
|
-
itself never persists it —
|
|
255
|
+
itself never persists it — identity API also sets the refresh cookie via
|
|
246
256
|
`Set-Cookie` and that's the canonical home for it.
|
|
247
257
|
|
|
248
258
|
### Passkey management (`/v1/me/passkeys`)
|
|
@@ -263,7 +273,7 @@ import {
|
|
|
263
273
|
|
|
264
274
|
const token = await getAccessToken();
|
|
265
275
|
await addPasskey({
|
|
266
|
-
apiUrl: "https://
|
|
276
|
+
apiUrl: "https://identity.authio.com",
|
|
267
277
|
projectId: "proj_123",
|
|
268
278
|
accessToken: token!,
|
|
269
279
|
email: user.email!,
|
|
@@ -284,13 +294,46 @@ await addPasskey({
|
|
|
284
294
|
Re-exported from `@useauthio/node`. Thrown by every helper and the
|
|
285
295
|
provider on failure. Shape: `{ code, message, status, requestId? }`.
|
|
286
296
|
|
|
297
|
+
`message` is always plain English and safe to show to users. Raw
|
|
298
|
+
browser or network errors are kept on `err.cause` for debugging.
|
|
299
|
+
|
|
300
|
+
### Handling risk checks (step-up and deny)
|
|
301
|
+
|
|
302
|
+
Authio's risk engine can ask for one more check (for example, a sign-in
|
|
303
|
+
from a new country) or refuse a sign-in. Sign-in helpers never return a
|
|
304
|
+
half-finished session; they throw:
|
|
305
|
+
|
|
306
|
+
| `err.code` | Class | What to do |
|
|
307
|
+
|------------|-------|------------|
|
|
308
|
+
| `step_up_required` | `AuthioStepUpRequiredError` | Send the user to `err.stepUpUrl` (the hosted step-up page). Also has `challengeId`, `requiredMethod`, `reasons`. |
|
|
309
|
+
| `sign_in_denied` | `AuthioSignInDeniedError` | Show `err.message` (the server's reason). `err.denyCode` is the machine code, for example `blocked_by_geo_policy`. |
|
|
310
|
+
| `invalid_response` | `AuthioError` | The server answered without a session. Ask the user to try again. |
|
|
311
|
+
|
|
312
|
+
```ts
|
|
313
|
+
import { signInWithPasskey, isStepUpRequired, AuthioError } from "@useauthio/react";
|
|
314
|
+
|
|
315
|
+
try {
|
|
316
|
+
const result = await signInWithPasskey({ apiUrl, projectId });
|
|
317
|
+
await handleSignInResult(result);
|
|
318
|
+
} catch (err) {
|
|
319
|
+
if (isStepUpRequired(err) && err.stepUpUrl) {
|
|
320
|
+
window.location.assign(err.stepUpUrl);
|
|
321
|
+
return;
|
|
322
|
+
}
|
|
323
|
+
setError(err instanceof AuthioError ? err.message : "Something went wrong. Please try again.");
|
|
324
|
+
}
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
`stepUpUrl` is `undefined` when auth-core predates the field or the
|
|
328
|
+
project has no hosted UI configured.
|
|
329
|
+
|
|
287
330
|
---
|
|
288
331
|
|
|
289
332
|
## When to use this vs. `@useauthio/nextjs`
|
|
290
333
|
|
|
291
334
|
| You have… | Use |
|
|
292
335
|
|-----------|-----|
|
|
293
|
-
| A pure SPA (Vite, CRA, Webpack) talking directly to
|
|
336
|
+
| A pure SPA (Vite, CRA, Webpack) talking directly to identity API via CORS | **`@useauthio/react`** (this package) |
|
|
294
337
|
| A Next.js app with a BFF (`/api/auth/*` route handlers) | [`@useauthio/nextjs`](https://github.com/authio-com/authio_nextjs) |
|
|
295
338
|
| A Remix / TanStack Start / Astro app | `@useauthio/react` for the client; your framework's loader/action helpers for the server |
|
|
296
339
|
|
|
@@ -298,9 +341,9 @@ The reason for the split: `@useauthio/nextjs` lives in the BFF cookie
|
|
|
298
341
|
world — it owns `authio_session` + `authio_refresh` HttpOnly cookies
|
|
299
342
|
on **your origin** and the SPA sees only `useUser()`-style hooks
|
|
300
343
|
pointed at `/api/auth/me`. `@useauthio/react` lives in the CORS world —
|
|
301
|
-
your SPA fetches `
|
|
344
|
+
your SPA fetches `identity.authio.com` directly with
|
|
302
345
|
`credentials: include`, and the refresh cookie is set on the
|
|
303
|
-
|
|
346
|
+
identity API origin. Both end up with the same DX in components, but
|
|
304
347
|
the network shape and the threat surface differ.
|
|
305
348
|
|
|
306
349
|
---
|
|
@@ -313,12 +356,12 @@ Security Policy so the browser allows it:
|
|
|
313
356
|
```http
|
|
314
357
|
Content-Security-Policy:
|
|
315
358
|
default-src 'self';
|
|
316
|
-
connect-src 'self' https://
|
|
359
|
+
connect-src 'self' https://identity.authio.com;
|
|
317
360
|
script-src 'self';
|
|
318
361
|
style-src 'self' 'unsafe-inline';
|
|
319
362
|
```
|
|
320
363
|
|
|
321
|
-
If you've moved
|
|
364
|
+
If you've moved identity API to a custom domain (e.g.
|
|
322
365
|
`auth.acme.com`), allowlist that host instead. The hosted sign-in UI
|
|
323
366
|
itself is reached via a top-level navigation (`window.location.assign`),
|
|
324
367
|
which is not subject to `connect-src`.
|
|
@@ -346,7 +389,7 @@ mode plus the refresh cookie is enough.
|
|
|
346
389
|
|
|
347
390
|
**The refresh token is NEVER stored in JS-accessible storage**,
|
|
348
391
|
regardless of which `storage` mode you choose. It rides only the
|
|
349
|
-
HttpOnly cookie that
|
|
392
|
+
HttpOnly cookie that identity API sets at `/v1/auth/refresh` and
|
|
350
393
|
`/v1/auth/passkey/login/verify`. `getAccessToken()` and the silent
|
|
351
394
|
refresh path both call those endpoints with `credentials: include`
|
|
352
395
|
to pick up the rotated token without ever surfacing the refresh
|
|
@@ -356,25 +399,51 @@ token to your code.
|
|
|
356
399
|
|
|
357
400
|
## CSRF guidance
|
|
358
401
|
|
|
359
|
-
If your SPA is hosted on a different origin than
|
|
360
|
-
`app.acme.com` calling `
|
|
402
|
+
If your SPA is hosted on a different origin than identity API (e.g.
|
|
403
|
+
`app.acme.com` calling `identity.authio.com`):
|
|
361
404
|
|
|
362
|
-
1.
|
|
363
|
-
The
|
|
405
|
+
1. Identity API's CORS allowlist must include your SPA origin.
|
|
406
|
+
The identity API operator adds it via the project settings.
|
|
364
407
|
2. The provider always uses `credentials: include` on
|
|
365
408
|
`/v1/auth/refresh` and `/v1/auth/sign-out`, so the browser sends
|
|
366
409
|
the refresh cookie on those calls.
|
|
367
|
-
3.
|
|
410
|
+
3. Identity API enforces a SameSite=None refresh cookie when the SPA
|
|
368
411
|
origin differs from the cookie origin, plus the per-project CORS
|
|
369
412
|
origin check — that's the line of defence against CSRF on the
|
|
370
413
|
refresh endpoint itself.
|
|
371
414
|
|
|
372
|
-
If your SPA is hosted on the SAME parent domain as
|
|
415
|
+
If your SPA is hosted on the SAME parent domain as identity API (e.g.
|
|
373
416
|
both under `*.acme.com`), the refresh cookie is a SameSite=Lax
|
|
374
417
|
first-party cookie and the cross-origin check is implicit.
|
|
375
418
|
|
|
376
419
|
---
|
|
377
420
|
|
|
421
|
+
## Locate (GPS + custom actions)
|
|
422
|
+
|
|
423
|
+
Capture GPS in the browser, then POST to **your backend**. The backend calls
|
|
424
|
+
management API with a secret key (`sk_live_…` / `sk_test_…`) — never expose
|
|
425
|
+
`sk_` in the browser:
|
|
426
|
+
|
|
427
|
+
```tsx
|
|
428
|
+
import { captureClientLocation } from "@useauthio/react";
|
|
429
|
+
|
|
430
|
+
const gps = await captureClientLocation({ enableHighAccuracy: true });
|
|
431
|
+
const result = await fetch("/api/locate/verify-wager", {
|
|
432
|
+
method: "POST",
|
|
433
|
+
headers: { "Content-Type": "application/json" },
|
|
434
|
+
body: JSON.stringify({ action: "wager_placed", client_location: gps }),
|
|
435
|
+
});
|
|
436
|
+
```
|
|
437
|
+
|
|
438
|
+
Server-side, use `@useauthio/node` → `authio.locate.verify({ action, client_location, user_id, … })`
|
|
439
|
+
against `https://manage.authio.com/v1/locate/verify`.
|
|
440
|
+
|
|
441
|
+
**React Native:** `@useauthio/react` is browser-only. Use native geolocation
|
|
442
|
+
(expo-location or `@react-native-community/geolocation`), POST to your backend,
|
|
443
|
+
same proxy pattern. Full JB migration guide: `authio_locate/docs/JB_MIGRATION_GUIDE.md`.
|
|
444
|
+
|
|
445
|
+
---
|
|
446
|
+
|
|
378
447
|
## License
|
|
379
448
|
|
|
380
449
|
MIT — see [LICENSE](./LICENSE).
|