@useauthio/react 0.2.3 → 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/CHANGELOG.md +57 -0
- package/README.md +85 -18
- package/dist/index.cjs +682 -12
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +375 -17
- package/dist/index.d.ts +375 -17
- package/dist/index.js +665 -15
- package/dist/index.js.map +1 -1
- package/package.json +2 -1
- package/src/PasskeyManager.tsx +164 -0
- package/src/activity.ts +95 -0
- package/src/device-signals.ts +86 -0
- package/src/index.ts +53 -2
- package/src/lobby-context.ts +8 -0
- package/src/locate.ts +42 -0
- package/src/passkeys.ts +247 -0
- package/src/provider.tsx +119 -14
- package/src/refresh.ts +41 -0
- package/src/sign-in.ts +189 -2
- package/src/telemetry.ts +11 -0
- package/src/types.ts +79 -0
- package/src/usePasskeys.ts +134 -0
- package/src/version.ts +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,63 @@ 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.0] — 2026-09-03
|
|
8
|
+
|
|
9
|
+
### Added
|
|
10
|
+
- **Session policy on the context.** `useAuthio().sessionPolicy` exposes the
|
|
11
|
+
effective session-lifecycle limits auth-core now reports in the
|
|
12
|
+
`session_policy` field of every envelope (`idleTimeoutMin`,
|
|
13
|
+
`absoluteMaxMin`, `accessTokenTtlMin`; minutes, `0` = no limit). `null` on
|
|
14
|
+
auth-core versions that predate the field. `signInWithPasskey` and
|
|
15
|
+
`verifyEmailOtp` results carry the same value, and `handleSignInResult`
|
|
16
|
+
accepts it.
|
|
17
|
+
- **Inactivity-aware silent refresh.** When the effective policy has an
|
|
18
|
+
inactivity timeout and the user has not interacted with the page since the
|
|
19
|
+
last refresh, the scheduled refresh is held until the next interaction
|
|
20
|
+
(pointer, key, touch, scroll, focus, or tab returning to the foreground)
|
|
21
|
+
instead of keeping an idle session alive. Projects without an inactivity
|
|
22
|
+
policy — and any auth-core that does not send `session_policy` — keep the
|
|
23
|
+
previous always-refresh behaviour, so existing apps are unaffected until
|
|
24
|
+
their project opts into an inactivity limit.
|
|
25
|
+
- New provider prop `idleRefresh: "defer" | "always"` (default `"defer"`) as
|
|
26
|
+
an escape hatch for apps whose background work needs a warm token while
|
|
27
|
+
the user is away.
|
|
28
|
+
- Telemetry events `refresh_deferred` (`reason: "hidden" | "idle"`) and
|
|
29
|
+
`refresh_resumed`.
|
|
30
|
+
- Exported `ActivityTracker`, `coerceSessionPolicy`, and the
|
|
31
|
+
`SessionPolicy` / `RawSessionPolicy` / `AuthioIdleRefreshMode` /
|
|
32
|
+
`RefreshDeferReason` types.
|
|
33
|
+
|
|
34
|
+
## [0.2.5] — 2026-07-01
|
|
35
|
+
|
|
36
|
+
### Added
|
|
37
|
+
- **Email OTP sign-in.** `sendEmailOtp({ email, redirectUri?, next?, organizationId? })`
|
|
38
|
+
and `verifyEmailOtp({ email, code, next?, organizationId?, clientLocation?, deviceSignals? })`
|
|
39
|
+
helpers for auth-core's `/v1/auth/email-otp/send` + `/verify`, mirroring the
|
|
40
|
+
hosted Lobby's body shapes. `verifyEmailOtp` throws a typed
|
|
41
|
+
`step_up_required` `AuthioError` when the risk engine withholds the session.
|
|
42
|
+
- **`signInWithPasskey` org/next forwarding.** Optional `next` and
|
|
43
|
+
`organizationId` are now included in the passkey login verify body when
|
|
44
|
+
provided. Older auth-core deployments ignore the fields; client-side token
|
|
45
|
+
handling is unchanged.
|
|
46
|
+
|
|
47
|
+
### Fixed
|
|
48
|
+
- `SDK_VERSION` (and the `X-Authio-SDK` header) had drifted from
|
|
49
|
+
`package.json` — re-synced.
|
|
50
|
+
|
|
51
|
+
## [0.2.4] — 2026-06-19
|
|
52
|
+
|
|
53
|
+
### Added
|
|
54
|
+
- **Passkey management for customer apps.** `listPasskeys`, `renamePasskey`,
|
|
55
|
+
`revokePasskey`, `mintPasskeyRegisterIntent`, `buildEnrollPasskeyUrl`, and
|
|
56
|
+
`enrollPasskey` helpers for `/v1/me/passkeys` and hosted-UI
|
|
57
|
+
`mode=add_credential` enrollment.
|
|
58
|
+
- **`usePasskeys` hook** and **`<PasskeyManager />`** drop-in component for
|
|
59
|
+
in-app device lists (list/rename/revoke on your origin; add via redirect to
|
|
60
|
+
the sign-in host).
|
|
61
|
+
- **`addPasskey()`** for embedded WebAuthn enrollment when your SPA shares
|
|
62
|
+
the sign-in origin (`canEnrollPasskeyEmbedded`).
|
|
63
|
+
|
|
7
64
|
## [0.2.3] — 2026-06-17
|
|
8
65
|
|
|
9
66
|
### 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,12 +246,46 @@ 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`, or any
|
|
249
|
+
`webauthn_cancelled`, or any identity API error code on a step failure.
|
|
243
250
|
|
|
244
251
|
The returned `refreshToken` is included for completeness but the SDK
|
|
245
|
-
itself never persists it —
|
|
252
|
+
itself never persists it — identity API also sets the refresh cookie via
|
|
246
253
|
`Set-Cookie` and that's the canonical home for it.
|
|
247
254
|
|
|
255
|
+
### Passkey management (`/v1/me/passkeys`)
|
|
256
|
+
|
|
257
|
+
After signup, let users add and manage passkeys on the sign-in origin
|
|
258
|
+
or from your SPA:
|
|
259
|
+
|
|
260
|
+
```ts
|
|
261
|
+
import {
|
|
262
|
+
addPasskey,
|
|
263
|
+
listPasskeys,
|
|
264
|
+
renamePasskey,
|
|
265
|
+
revokePasskey,
|
|
266
|
+
enrollPasskey,
|
|
267
|
+
usePasskeys,
|
|
268
|
+
PasskeyManager,
|
|
269
|
+
} from "@useauthio/react";
|
|
270
|
+
|
|
271
|
+
const token = await getAccessToken();
|
|
272
|
+
await addPasskey({
|
|
273
|
+
apiUrl: "https://identity.authio.com",
|
|
274
|
+
projectId: "proj_123",
|
|
275
|
+
accessToken: token!,
|
|
276
|
+
email: user.email!,
|
|
277
|
+
});
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
- `addPasskey` — inline WebAuthn on the **current origin** (use when
|
|
281
|
+
your app runs on the same host as the hosted sign-in UI / custom
|
|
282
|
+
`auth.` domain).
|
|
283
|
+
- `enrollPasskey` — redirects to hosted UI `?mode=add_credential` when
|
|
284
|
+
the SPA origin differs from the WebAuthn RP ID.
|
|
285
|
+
- `listPasskeys` / `renamePasskey` / `revokePasskey` — CRUD against
|
|
286
|
+
`/v1/me/passkeys` with a session `accessToken`.
|
|
287
|
+
- `<PasskeyManager />` + `usePasskeys()` — drop-in UI for customer apps.
|
|
288
|
+
|
|
248
289
|
### `AuthioError`
|
|
249
290
|
|
|
250
291
|
Re-exported from `@useauthio/node`. Thrown by every helper and the
|
|
@@ -256,7 +297,7 @@ provider on failure. Shape: `{ code, message, status, requestId? }`.
|
|
|
256
297
|
|
|
257
298
|
| You have… | Use |
|
|
258
299
|
|-----------|-----|
|
|
259
|
-
| A pure SPA (Vite, CRA, Webpack) talking directly to
|
|
300
|
+
| A pure SPA (Vite, CRA, Webpack) talking directly to identity API via CORS | **`@useauthio/react`** (this package) |
|
|
260
301
|
| A Next.js app with a BFF (`/api/auth/*` route handlers) | [`@useauthio/nextjs`](https://github.com/authio-com/authio_nextjs) |
|
|
261
302
|
| A Remix / TanStack Start / Astro app | `@useauthio/react` for the client; your framework's loader/action helpers for the server |
|
|
262
303
|
|
|
@@ -264,9 +305,9 @@ The reason for the split: `@useauthio/nextjs` lives in the BFF cookie
|
|
|
264
305
|
world — it owns `authio_session` + `authio_refresh` HttpOnly cookies
|
|
265
306
|
on **your origin** and the SPA sees only `useUser()`-style hooks
|
|
266
307
|
pointed at `/api/auth/me`. `@useauthio/react` lives in the CORS world —
|
|
267
|
-
your SPA fetches `
|
|
308
|
+
your SPA fetches `identity.authio.com` directly with
|
|
268
309
|
`credentials: include`, and the refresh cookie is set on the
|
|
269
|
-
|
|
310
|
+
identity API origin. Both end up with the same DX in components, but
|
|
270
311
|
the network shape and the threat surface differ.
|
|
271
312
|
|
|
272
313
|
---
|
|
@@ -279,12 +320,12 @@ Security Policy so the browser allows it:
|
|
|
279
320
|
```http
|
|
280
321
|
Content-Security-Policy:
|
|
281
322
|
default-src 'self';
|
|
282
|
-
connect-src 'self' https://
|
|
323
|
+
connect-src 'self' https://identity.authio.com;
|
|
283
324
|
script-src 'self';
|
|
284
325
|
style-src 'self' 'unsafe-inline';
|
|
285
326
|
```
|
|
286
327
|
|
|
287
|
-
If you've moved
|
|
328
|
+
If you've moved identity API to a custom domain (e.g.
|
|
288
329
|
`auth.acme.com`), allowlist that host instead. The hosted sign-in UI
|
|
289
330
|
itself is reached via a top-level navigation (`window.location.assign`),
|
|
290
331
|
which is not subject to `connect-src`.
|
|
@@ -312,7 +353,7 @@ mode plus the refresh cookie is enough.
|
|
|
312
353
|
|
|
313
354
|
**The refresh token is NEVER stored in JS-accessible storage**,
|
|
314
355
|
regardless of which `storage` mode you choose. It rides only the
|
|
315
|
-
HttpOnly cookie that
|
|
356
|
+
HttpOnly cookie that identity API sets at `/v1/auth/refresh` and
|
|
316
357
|
`/v1/auth/passkey/login/verify`. `getAccessToken()` and the silent
|
|
317
358
|
refresh path both call those endpoints with `credentials: include`
|
|
318
359
|
to pick up the rotated token without ever surfacing the refresh
|
|
@@ -322,25 +363,51 @@ token to your code.
|
|
|
322
363
|
|
|
323
364
|
## CSRF guidance
|
|
324
365
|
|
|
325
|
-
If your SPA is hosted on a different origin than
|
|
326
|
-
`app.acme.com` calling `
|
|
366
|
+
If your SPA is hosted on a different origin than identity API (e.g.
|
|
367
|
+
`app.acme.com` calling `identity.authio.com`):
|
|
327
368
|
|
|
328
|
-
1.
|
|
329
|
-
The
|
|
369
|
+
1. Identity API's CORS allowlist must include your SPA origin.
|
|
370
|
+
The identity API operator adds it via the project settings.
|
|
330
371
|
2. The provider always uses `credentials: include` on
|
|
331
372
|
`/v1/auth/refresh` and `/v1/auth/sign-out`, so the browser sends
|
|
332
373
|
the refresh cookie on those calls.
|
|
333
|
-
3.
|
|
374
|
+
3. Identity API enforces a SameSite=None refresh cookie when the SPA
|
|
334
375
|
origin differs from the cookie origin, plus the per-project CORS
|
|
335
376
|
origin check — that's the line of defence against CSRF on the
|
|
336
377
|
refresh endpoint itself.
|
|
337
378
|
|
|
338
|
-
If your SPA is hosted on the SAME parent domain as
|
|
379
|
+
If your SPA is hosted on the SAME parent domain as identity API (e.g.
|
|
339
380
|
both under `*.acme.com`), the refresh cookie is a SameSite=Lax
|
|
340
381
|
first-party cookie and the cross-origin check is implicit.
|
|
341
382
|
|
|
342
383
|
---
|
|
343
384
|
|
|
385
|
+
## Locate (GPS + custom actions)
|
|
386
|
+
|
|
387
|
+
Capture GPS in the browser, then POST to **your backend**. The backend calls
|
|
388
|
+
management API with a secret key (`sk_live_…` / `sk_test_…`) — never expose
|
|
389
|
+
`sk_` in the browser:
|
|
390
|
+
|
|
391
|
+
```tsx
|
|
392
|
+
import { captureClientLocation } from "@useauthio/react";
|
|
393
|
+
|
|
394
|
+
const gps = await captureClientLocation({ enableHighAccuracy: true });
|
|
395
|
+
const result = await fetch("/api/locate/verify-wager", {
|
|
396
|
+
method: "POST",
|
|
397
|
+
headers: { "Content-Type": "application/json" },
|
|
398
|
+
body: JSON.stringify({ action: "wager_placed", client_location: gps }),
|
|
399
|
+
});
|
|
400
|
+
```
|
|
401
|
+
|
|
402
|
+
Server-side, use `@useauthio/node` → `authio.locate.verify({ action, client_location, user_id, … })`
|
|
403
|
+
against `https://manage.authio.com/v1/locate/verify`.
|
|
404
|
+
|
|
405
|
+
**React Native:** `@useauthio/react` is browser-only. Use native geolocation
|
|
406
|
+
(expo-location or `@react-native-community/geolocation`), POST to your backend,
|
|
407
|
+
same proxy pattern. Full JB migration guide: `authio_locate/docs/JB_MIGRATION_GUIDE.md`.
|
|
408
|
+
|
|
409
|
+
---
|
|
410
|
+
|
|
344
411
|
## License
|
|
345
412
|
|
|
346
413
|
MIT — see [LICENSE](./LICENSE).
|