@useauthio/react 0.2.4 → 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 +44 -0
- package/README.md +52 -19
- package/dist/index.cjs +303 -12
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +265 -25
- package/dist/index.d.ts +265 -25
- package/dist/index.js +296 -14
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/src/activity.ts +95 -0
- package/src/device-signals.ts +86 -0
- package/src/index.ts +29 -2
- package/src/lobby-context.ts +8 -0
- package/src/locate.ts +42 -0
- package/src/provider.tsx +109 -14
- package/src/refresh.ts +41 -0
- package/src/sign-in.ts +189 -2
- package/src/telemetry.ts +11 -0
- package/src/types.ts +71 -0
- package/src/version.ts +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,50 @@ 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
|
+
|
|
7
51
|
## [0.2.4] — 2026-06-19
|
|
8
52
|
|
|
9
53
|
### 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,10 @@ 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
|
|
|
248
255
|
### Passkey management (`/v1/me/passkeys`)
|
|
@@ -263,7 +270,7 @@ import {
|
|
|
263
270
|
|
|
264
271
|
const token = await getAccessToken();
|
|
265
272
|
await addPasskey({
|
|
266
|
-
apiUrl: "https://
|
|
273
|
+
apiUrl: "https://identity.authio.com",
|
|
267
274
|
projectId: "proj_123",
|
|
268
275
|
accessToken: token!,
|
|
269
276
|
email: user.email!,
|
|
@@ -290,7 +297,7 @@ provider on failure. Shape: `{ code, message, status, requestId? }`.
|
|
|
290
297
|
|
|
291
298
|
| You have… | Use |
|
|
292
299
|
|-----------|-----|
|
|
293
|
-
| 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) |
|
|
294
301
|
| A Next.js app with a BFF (`/api/auth/*` route handlers) | [`@useauthio/nextjs`](https://github.com/authio-com/authio_nextjs) |
|
|
295
302
|
| A Remix / TanStack Start / Astro app | `@useauthio/react` for the client; your framework's loader/action helpers for the server |
|
|
296
303
|
|
|
@@ -298,9 +305,9 @@ The reason for the split: `@useauthio/nextjs` lives in the BFF cookie
|
|
|
298
305
|
world — it owns `authio_session` + `authio_refresh` HttpOnly cookies
|
|
299
306
|
on **your origin** and the SPA sees only `useUser()`-style hooks
|
|
300
307
|
pointed at `/api/auth/me`. `@useauthio/react` lives in the CORS world —
|
|
301
|
-
your SPA fetches `
|
|
308
|
+
your SPA fetches `identity.authio.com` directly with
|
|
302
309
|
`credentials: include`, and the refresh cookie is set on the
|
|
303
|
-
|
|
310
|
+
identity API origin. Both end up with the same DX in components, but
|
|
304
311
|
the network shape and the threat surface differ.
|
|
305
312
|
|
|
306
313
|
---
|
|
@@ -313,12 +320,12 @@ Security Policy so the browser allows it:
|
|
|
313
320
|
```http
|
|
314
321
|
Content-Security-Policy:
|
|
315
322
|
default-src 'self';
|
|
316
|
-
connect-src 'self' https://
|
|
323
|
+
connect-src 'self' https://identity.authio.com;
|
|
317
324
|
script-src 'self';
|
|
318
325
|
style-src 'self' 'unsafe-inline';
|
|
319
326
|
```
|
|
320
327
|
|
|
321
|
-
If you've moved
|
|
328
|
+
If you've moved identity API to a custom domain (e.g.
|
|
322
329
|
`auth.acme.com`), allowlist that host instead. The hosted sign-in UI
|
|
323
330
|
itself is reached via a top-level navigation (`window.location.assign`),
|
|
324
331
|
which is not subject to `connect-src`.
|
|
@@ -346,7 +353,7 @@ mode plus the refresh cookie is enough.
|
|
|
346
353
|
|
|
347
354
|
**The refresh token is NEVER stored in JS-accessible storage**,
|
|
348
355
|
regardless of which `storage` mode you choose. It rides only the
|
|
349
|
-
HttpOnly cookie that
|
|
356
|
+
HttpOnly cookie that identity API sets at `/v1/auth/refresh` and
|
|
350
357
|
`/v1/auth/passkey/login/verify`. `getAccessToken()` and the silent
|
|
351
358
|
refresh path both call those endpoints with `credentials: include`
|
|
352
359
|
to pick up the rotated token without ever surfacing the refresh
|
|
@@ -356,25 +363,51 @@ token to your code.
|
|
|
356
363
|
|
|
357
364
|
## CSRF guidance
|
|
358
365
|
|
|
359
|
-
If your SPA is hosted on a different origin than
|
|
360
|
-
`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`):
|
|
361
368
|
|
|
362
|
-
1.
|
|
363
|
-
The
|
|
369
|
+
1. Identity API's CORS allowlist must include your SPA origin.
|
|
370
|
+
The identity API operator adds it via the project settings.
|
|
364
371
|
2. The provider always uses `credentials: include` on
|
|
365
372
|
`/v1/auth/refresh` and `/v1/auth/sign-out`, so the browser sends
|
|
366
373
|
the refresh cookie on those calls.
|
|
367
|
-
3.
|
|
374
|
+
3. Identity API enforces a SameSite=None refresh cookie when the SPA
|
|
368
375
|
origin differs from the cookie origin, plus the per-project CORS
|
|
369
376
|
origin check — that's the line of defence against CSRF on the
|
|
370
377
|
refresh endpoint itself.
|
|
371
378
|
|
|
372
|
-
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.
|
|
373
380
|
both under `*.acme.com`), the refresh cookie is a SameSite=Lax
|
|
374
381
|
first-party cookie and the cross-origin check is implicit.
|
|
375
382
|
|
|
376
383
|
---
|
|
377
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
|
+
|
|
378
411
|
## License
|
|
379
412
|
|
|
380
413
|
MIT — see [LICENSE](./LICENSE).
|