@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 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 auth-core via CORS. If you have a
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
- auth-core JWKS before trusting it.
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) | — | Auth-core base URL, e.g. `"https://auth-api.authio.com"`. |
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 auth-core
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`, or any auth-core error code on a step failure.
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 — auth-core also sets the refresh cookie via
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://auth-api.authio.com",
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 auth-core via CORS | **`@useauthio/react`** (this package) |
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 `auth-api.authio.com` directly with
344
+ your SPA fetches `identity.authio.com` directly with
302
345
  `credentials: include`, and the refresh cookie is set on the
303
- auth-core origin. Both end up with the same DX in components, but
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://auth-api.authio.com;
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 auth-core to a custom domain (e.g.
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 auth-core sets at `/v1/auth/refresh` and
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 auth-core (e.g.
360
- `app.acme.com` calling `auth-api.authio.com`):
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. Auth-core's CORS allowlist must include your SPA origin.
363
- The auth-core operator adds it via the project settings.
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. Auth-core enforces a SameSite=None refresh cookie when the SPA
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 auth-core (e.g.
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).