@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 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 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,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 auth-core error code on a step failure.
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 — auth-core also sets the refresh cookie via
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 auth-core via CORS | **`@useauthio/react`** (this package) |
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 `auth-api.authio.com` directly with
308
+ your SPA fetches `identity.authio.com` directly with
268
309
  `credentials: include`, and the refresh cookie is set on the
269
- auth-core origin. Both end up with the same DX in components, but
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://auth-api.authio.com;
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 auth-core to a custom domain (e.g.
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 auth-core sets at `/v1/auth/refresh` and
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 auth-core (e.g.
326
- `app.acme.com` calling `auth-api.authio.com`):
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. Auth-core's CORS allowlist must include your SPA origin.
329
- The auth-core operator adds it via the project settings.
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. Auth-core enforces a SameSite=None refresh cookie when the SPA
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 auth-core (e.g.
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).