@lumoauth/react 0.0.0-stage → 1.1.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 LumoAuth LLC
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,643 @@
1
- # Temporary Holding Version
1
+ # @lumoauth/react
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm](https://img.shields.io/npm/v/@lumoauth/react.svg)](https://www.npmjs.com/package/@lumoauth/react)
4
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
5
+
6
+ `@lumoauth/react` adds LumoAuth sign-in, user menus and access checks to a React app. You wrap
7
+ the app in `<LumoAuthProvider>`, then use ready-made components such as `<SignIn>`,
8
+ `<UserButton>` and `<Protect>`, or hooks such as `useAuth()` and `usePermission()`. Users sign
9
+ in with OAuth 2.0 and PKCE by default.
10
+
11
+ It is part of the [LumoAuth JavaScript SDK](../../README.md), and it is built on
12
+ [`@lumoauth/client`](../client/README.md).
13
+
14
+ ## Contents
15
+
16
+ - [Is this the right package?](#is-this-the-right-package)
17
+ - [Requirements](#requirements)
18
+ - [Install](#install)
19
+ - [Quick start](#quick-start)
20
+ - [Core concepts](#core-concepts)
21
+ - [Configuration](#configuration)
22
+ - [Components](#components)
23
+ - [Sign-in and sign-up](#sign-in-and-sign-up)
24
+ - [User](#user)
25
+ - [Access checks](#access-checks)
26
+ - [Show content by sign-in state](#show-content-by-sign-in-state)
27
+ - [Unstyled buttons](#unstyled-buttons)
28
+ - [Hooks](#hooks)
29
+ - [Common patterns](#common-patterns)
30
+ - [Appearance](#appearance)
31
+ - [Sign-in strategies](#sign-in-strategies)
32
+ - [Errors](#errors)
33
+ - [API reference](#api-reference)
34
+ - [Troubleshooting](#troubleshooting)
35
+ - [Versioning and compatibility](#versioning-and-compatibility)
36
+ - [Related packages](#related-packages)
37
+ - [Licence](#licence)
38
+
39
+ ## Is this the right package?
40
+
41
+ | You are building… | Use |
42
+ |---|---|
43
+ | A React 18+ single-page app (Vite, Remix, React Router and similar) | **This package** |
44
+ | A Next.js App Router app | [`@lumoauth/nextjs`](../nextjs/README.md). It re-exports everything here and adds server-side sessions. |
45
+ | An app in Vue, Svelte, Angular or plain JavaScript | [`@lumoauth/client`](../client/README.md) |
46
+ | Server code | [`@lumoauth/backend`](../backend/README.md) or [`@lumoauth/express`](../express/README.md) |
47
+
48
+ ## Requirements
49
+
50
+ - React and React DOM 18 or newer (peer dependencies)
51
+ - Node 18 or newer for your build
52
+ - A LumoAuth organization and a **public** OAuth client with PKCE. Register your callback URL as a
53
+ redirect URI, and add your app's origin to the client's allowed origins.
54
+
55
+ ## Install
56
+
57
+ ```bash
58
+ npm install @lumoauth/react
59
+ ```
60
+
61
+ `@lumoauth/client` is installed with it and re-exported as `LumoAuth`, so one install is enough.
62
+
63
+ ## Quick start
64
+
65
+ **1. Wrap the app in the provider.**
66
+
67
+ ```tsx
68
+ import { LumoAuthProvider } from '@lumoauth/react';
69
+
70
+ export function App() {
71
+ return (
72
+ <LumoAuthProvider
73
+ domain="https://app.lumoauth.dev" // EU region: https://eu.app.lumoauth.dev
74
+ orgId="acme-corp"
75
+ clientId="your-client-id"
76
+ afterSignInUrl="/dashboard"
77
+ >
78
+ <Routes />
79
+ </LumoAuthProvider>
80
+ );
81
+ }
82
+ ```
83
+
84
+ **2. Add a callback page.** By default the provider sends users back to
85
+ `<your origin>/auth/callback`. Mount `<AuthCallback>` on that route:
86
+
87
+ ```tsx
88
+ import { AuthCallback } from '@lumoauth/react';
89
+
90
+ export function CallbackPage() {
91
+ return <AuthCallback afterSignInUrl="/dashboard" />;
92
+ }
93
+ ```
94
+
95
+ **3. Show a sign-in button or the user menu.**
96
+
97
+ ```tsx
98
+ import { SignedIn, SignedOut, SignInButton, UserButton } from '@lumoauth/react';
99
+
100
+ export function Header() {
101
+ return (
102
+ <nav>
103
+ <SignedOut><SignInButton>Sign in</SignInButton></SignedOut>
104
+ <SignedIn><UserButton showName /></SignedIn>
105
+ </nav>
106
+ );
107
+ }
108
+ ```
109
+
110
+ **4. Show content only to users who hold a permission.**
111
+
112
+ ```tsx
113
+ import { Protect } from '@lumoauth/react';
114
+
115
+ <Protect permission="admin.dashboard" fallback={<p>You do not have access.</p>}>
116
+ <AdminPanel />
117
+ </Protect>
118
+ ```
119
+
120
+ ## Core concepts
121
+
122
+ **The provider holds the session.** `<LumoAuthProvider>` signs the user in, stores the tokens,
123
+ refreshes the access token before it expires, and shares the session across tabs. Every component
124
+ and hook reads from it, so the provider must wrap them.
125
+
126
+ **Checks run as the signed-in user.** `usePermission`, `useZanzibar`, `useAbac` and `<Protect>`
127
+ call LumoAuth with the user's access token. They hide content in the browser, but they do not
128
+ protect data. Your API must check access again on the server.
129
+
130
+ **Scopes.** The provider requests `openid profile email` at sign-in unless you pass a `scope`
131
+ prop. Permission and relationship checks need nothing more. ABAC checks need `abac:read`, and
132
+ listing the user's permissions needs `authz:read`. Add them to `scope`, and allow them on the
133
+ OAuth client:
134
+
135
+ ```tsx
136
+ <LumoAuthProvider
137
+ domain="https://app.lumoauth.dev"
138
+ orgId="acme-corp"
139
+ clientId="client_…"
140
+ scope="openid profile email abac:read authz:read"
141
+ >
142
+ ```
143
+
144
+ The full scope table is in the [client README](../client/README.md#scopes).
145
+
146
+ ## Configuration
147
+
148
+ `<LumoAuthProvider>` props:
149
+
150
+ | Prop | Type | Default | Description |
151
+ |---|---|---|---|
152
+ | `domain` | `string` | required | Root URL of LumoAuth |
153
+ | `orgId` | `string` | required | Organization slug |
154
+ | `clientId` | `string` | required | OAuth client ID |
155
+ | `redirectUri` | `string` | `<origin>/auth/callback` | Callback URL. It must be registered on the OAuth client. |
156
+ | `scope` | `string` | `'openid profile email'` | Space-separated scopes for sign-in and sign-up. Add `abac:read` for `useAbac` and `<Protect abac>`, and `authz:read` for `listSlugs()`. The OAuth client must allow each scope. |
157
+ | `afterSignInUrl` | `string` | `'/'` | Where `<AuthCallback>` sends the user after sign-in |
158
+ | `afterSignUpUrl` | `string` | none | Where to go after sign-up |
159
+ | `afterSignOutUrl` | `string` | `'/'` | Where to go after sign-out. Register it as a post-logout redirect URI on the client. |
160
+ | `authStrategy` | `'pkce' \| 'password'` | `'pkce'` | See [Sign-in strategies](#sign-in-strategies) |
161
+ | `storage` | `TokenStorage` | `sessionStorage` in a browser, memory on a server | Where tokens are stored. Import an adapter from `@lumoauth/client`. |
162
+ | `crossTab` | `boolean` | `true` | Share the session across tabs. One tab does each refresh, and the others receive the result. |
163
+ | `children` | `ReactNode` | required | Your app |
164
+
165
+ **Where tokens are stored.** The default, `sessionStorage`, keeps one session per tab and clears
166
+ it when the tab closes. `localStorageAdapter()` shares the session across tabs and browser
167
+ restarts. `cookieStorageAdapter()` keeps tokens in an httpOnly cookie that scripts cannot read,
168
+ which is the only option that protects them from cross-site scripting. It needs a same-origin
169
+ server that serves a session endpoint, such as the one in `@lumoauth/nextjs`. The
170
+ [client README](../client/README.md#choose-where-tokens-are-stored) compares the adapters.
171
+
172
+ ```tsx
173
+ import { localStorageAdapter } from '@lumoauth/client';
174
+
175
+ <LumoAuthProvider domain={domain} orgId={orgId} clientId={clientId} storage={localStorageAdapter()}>
176
+ ```
177
+
178
+ Create the adapter once, outside the component, or with `useMemo`. A new adapter on each render
179
+ rebuilds the session.
180
+
181
+ ## Components
182
+
183
+ ### Sign-in and sign-up
184
+
185
+ **`<SignIn>`** renders a sign-in card. In PKCE mode it shows social buttons, if you list any, and
186
+ a button that redirects to the LumoAuth sign-in page. In password mode it shows an email and
187
+ password form.
188
+
189
+ ```tsx
190
+ <SignIn afterSignInUrl="/dashboard" signUpUrl="/sign-up" socialProviders={['google', 'github']} />
191
+ ```
192
+
193
+ | Prop | Type | Description |
194
+ |---|---|---|
195
+ | `afterSignInUrl` | `string` | Where to go after sign-in |
196
+ | `signUpUrl` | `string` | Link to your sign-up page |
197
+ | `socialProviders` | `string[]` | Providers to show. The default is `[]`. Each button sends the user straight to that provider. If the organization has not set the provider up, the user sees the LumoAuth sign-in page instead. Icons are included for `google`, `github`, `microsoft` and `apple`. |
198
+ | `appearance` | `AppearanceProps` | See [Appearance](#appearance) |
199
+
200
+ The SDK has no default list of providers. An unauthenticated page cannot read which providers
201
+ the organization has turned on, so you list them yourself.
202
+
203
+ **`<SignUp>`** renders a sign-up card. In PKCE mode it sends the user to the LumoAuth registration
204
+ page. Password mode has no inline registration, because LumoAuth has no JSON registration
205
+ endpoint.
206
+
207
+ ```tsx
208
+ <SignUp afterSignUpUrl="/onboarding" signInUrl="/sign-in" />
209
+ ```
210
+
211
+ **`<AuthCallback>`** finishes sign-in on your callback route. It checks the `state`, exchanges the
212
+ code for tokens, loads the user and redirects.
213
+
214
+ ```tsx
215
+ <AuthCallback
216
+ afterSignInUrl="/dashboard"
217
+ loading={<Spinner />}
218
+ error={(message) => <ErrorCard message={message} />}
219
+ />
220
+ ```
221
+
222
+ | Prop | Type | Description |
223
+ |---|---|---|
224
+ | `afterSignInUrl` | `string` | Where to go on success. Falls back to the provider's `afterSignInUrl`, then `/`. |
225
+ | `loading` | `ReactNode` | Shown during the exchange |
226
+ | `error` | `ReactNode \| (message: string) => ReactNode` | Shown when sign-in fails |
227
+
228
+ ### User
229
+
230
+ **`<UserButton>`** shows the user's avatar with a menu for the account and sign-out. It renders
231
+ nothing when nobody is signed in.
232
+
233
+ ```tsx
234
+ <UserButton showName afterSignOutUrl="/" />
235
+ ```
236
+
237
+ | Prop | Type | Default | Description |
238
+ |---|---|---|---|
239
+ | `showName` | `boolean` | `false` | Show the display name next to the avatar |
240
+ | `afterSignOutUrl` | `string` | provider value, then `'/'` | Where to go after sign-out |
241
+ | `appearance` | `AppearanceProps` | none | Style overrides |
242
+
243
+ **`<UserAvatar>`** shows the user's picture or initials. It shows a placeholder icon when nobody
244
+ is signed in.
245
+
246
+ ```tsx
247
+ <UserAvatar />
248
+ <UserAvatar size={48} shape="square" />
249
+ ```
250
+
251
+ | Prop | Type | Default |
252
+ |---|---|---|
253
+ | `size` | `number` (pixels) | `32` |
254
+ | `shape` | `'circle' \| 'square'` | `'circle'` |
255
+ | `appearance` | `AppearanceProps` | none |
256
+
257
+ **`<UserProfile>`** shows a profile card with account details, security status, roles, groups and
258
+ a sign-out button.
259
+
260
+ ```tsx
261
+ <UserProfile afterSignOutUrl="/" />
262
+ <UserProfile mode="compact" /> {/* account details only */}
263
+ ```
264
+
265
+ | Prop | Type | Default | Description |
266
+ |---|---|---|---|
267
+ | `mode` | `'full' \| 'compact'` | `'full'` | `'compact'` hides the security and roles sections |
268
+ | `afterSignOutUrl` | `string` | none | Where to go after sign-out |
269
+ | `appearance` | `AppearanceProps` | none | Style overrides |
270
+
271
+ ### Access checks
272
+
273
+ **`<Protect>`** renders its children only when a check allows it. Pass exactly one of
274
+ `permission`, `zanzibar` or `abac`. While the check runs, and when it is denied, `<Protect>`
275
+ renders `fallback`.
276
+
277
+ ```tsx
278
+ // A permission (RBAC)
279
+ <Protect permission="admin.dashboard" fallback={<p>You do not have access.</p>}>
280
+ <AdminPanel />
281
+ </Protect>
282
+
283
+ // A relationship (Zanzibar). Without subject, the check is about the signed-in user.
284
+ <Protect zanzibar={{ object: 'document:readme', relation: 'editor' }}>
285
+ <EditButton />
286
+ </Protect>
287
+
288
+ // An attribute policy (ABAC). Needs abac:read on the token.
289
+ <Protect abac={{ resourceType: 'document', action: 'delete', resourceId: 'doc-123' }}>
290
+ <DeleteButton />
291
+ </Protect>
292
+ ```
293
+
294
+ | Prop | Type | Description |
295
+ |---|---|---|
296
+ | `permission` | `string` | Permission slug |
297
+ | `zanzibar` | `{ object, relation, subject? }` | Relationship check. Without `subject`, the SDK asks about `user:<sub>`, where `<sub>` is the signed-in user's subject. When nobody is signed in, `<Protect>` renders `fallback` and sends no request. |
298
+ | `abac` | `{ resourceType, action, resourceId? }` | ABAC check |
299
+ | `fallback` | `ReactNode` | Shown while checking and when denied. Default: nothing. |
300
+ | `children` | `ReactNode` | Shown when allowed |
301
+
302
+ Any error during the check, such as a missing scope, counts as denied.
303
+
304
+ ### Show content by sign-in state
305
+
306
+ ```tsx
307
+ <SignedIn><p>Welcome back.</p></SignedIn>
308
+ <SignedOut><SignIn /></SignedOut>
309
+ ```
310
+
311
+ `<SignedIn>` renders its children only when a user is signed in. `<SignedOut>` renders them only
312
+ when nobody is. Neither renders anything while the session is loading.
313
+
314
+ **`<RedirectToSignIn>`** starts sign-in as soon as it renders. In PKCE mode it sends the user to
315
+ LumoAuth. In password mode it sends the user to `signInUrl`, when you pass one.
316
+
317
+ ```tsx
318
+ <SignedOut><RedirectToSignIn /></SignedOut>
319
+ <SignedIn><Dashboard /></SignedIn>
320
+ ```
321
+
322
+ ### Unstyled buttons
323
+
324
+ These buttons have no styling of their own. Put your own markup inside them.
325
+
326
+ ```tsx
327
+ <SignInButton><button className="btn">Log in</button></SignInButton>
328
+ <SignUpButton signUpUrl="/register" />
329
+ <SignOutButton afterSignOutUrl="/"><button className="btn">Log out</button></SignOutButton>
330
+ ```
331
+
332
+ | Component | Props | What a click does |
333
+ |---|---|---|
334
+ | `<SignInButton>` | `children?`, `signInUrl?`, `className?` | PKCE mode: starts sign-in. Password mode: goes to `signInUrl`. |
335
+ | `<SignUpButton>` | `children?`, `signUpUrl?`, `className?` | Goes to `signUpUrl` |
336
+ | `<SignOutButton>` | `children?`, `afterSignOutUrl?`, `className?` | Signs the user out, then redirects |
337
+
338
+ ## Hooks
339
+
340
+ Every hook must be called inside `<LumoAuthProvider>`.
341
+
342
+ **`useAuth()`** returns the full auth context.
343
+
344
+ ```tsx
345
+ const { user, isSignedIn, isLoaded, signIn, signOut, getToken } = useAuth();
346
+
347
+ if (!isLoaded) return <p>Loading…</p>;
348
+ if (!isSignedIn) return <button onClick={() => signIn()}>Sign in</button>;
349
+ return <button onClick={() => signOut()}>Sign out {user!.displayName}</button>;
350
+ ```
351
+
352
+ | Property | Type | Description |
353
+ |---|---|---|
354
+ | `user` | `LumoAuthUser \| null` | The signed-in user |
355
+ | `status` | `'loading' \| 'authenticated' \| 'unauthenticated'` | Session status |
356
+ | `isLoaded` | `boolean` | The first session check has finished |
357
+ | `isSignedIn` | `boolean` | A user is signed in |
358
+ | `signIn(email?, password?)` | function | PKCE mode: call with no arguments to redirect to LumoAuth. Password mode: pass the email and password. |
359
+ | `signInWithRedirect()` | function | Starts the PKCE redirect in either mode |
360
+ | `signInWithSocial(provider)` | function | Starts the PKCE redirect straight to a social provider, such as `'google'` |
361
+ | `signUp(params)` | function | PKCE mode: sends the user to the registration page. Password mode: throws, because inline registration is not available. |
362
+ | `signOut({ afterSignOutUrl? })` | function | Revokes the access token, clears local tokens, and ends the LumoAuth session through the logout endpoint |
363
+ | `getToken()` | `() => Promise<string \| null>` | A valid access token. It refreshes first when needed. |
364
+ | `handleCallback()` | function | Exchanges the code on the callback page. `<AuthCallback>` calls it for you. |
365
+ | `sendMagicLink(email, redirectUri?)` | function | Emails a sign-in link |
366
+ | `checkEmail(email)` | `(email) => Promise<EmailCheckResult>` | Reports the sign-in methods for an email address |
367
+ | `authStrategy` | `'pkce' \| 'password'` | The strategy in use |
368
+ | `config` | object | The provider's `domain`, `orgId`, `clientId` and redirect URLs |
369
+
370
+ **`useUser()`** returns the signed-in `LumoAuthUser`, or `null`.
371
+
372
+ | Field | Type | Description |
373
+ |---|---|---|
374
+ | `id` | `string \| number` | User ID (the OIDC `sub`) |
375
+ | `email` | `string` | Primary email address |
376
+ | `firstName`, `lastName` | `string \| undefined` | Name parts |
377
+ | `displayName` | `string` | The name, or the email when there is no name |
378
+ | `avatarUrl` | `string \| undefined` | Profile picture |
379
+ | `emailVerified` | `boolean` | Whether the email address is verified |
380
+ | `mfaEnabled` | `boolean` | From the `mfa_enabled` claim; `false` when absent |
381
+ | `roles`, `groups` | `string[]` | From the `roles` and `groups` claims; empty when absent |
382
+ | `sub` | `string \| undefined` | OIDC subject |
383
+ | `claims` | `Record<string, unknown>` | Every claim from the UserInfo response |
384
+
385
+ The user comes from the OIDC UserInfo endpoint. A field is empty when the response does not
386
+ contain it.
387
+
388
+ **`useSignIn()`** returns `{ signIn, signInWithRedirect, isLoading }`.
389
+
390
+ **`useSession()`** returns `{ isActive, isLoaded, getToken, status }`. Use `getToken()` to call
391
+ your own API:
392
+
393
+ ```tsx
394
+ const { getToken } = useSession();
395
+ const res = await fetch('/api/data', { headers: { Authorization: `Bearer ${await getToken()}` } });
396
+ ```
397
+
398
+ **`useLumoAuth()`** returns a `LumoAuth` client from `@lumoauth/client`. Its token comes from the
399
+ session. Use it for any call that the hooks do not cover.
400
+
401
+ ```tsx
402
+ const client = useLumoAuth();
403
+ const canEdit = await client.permissions.check('document.edit');
404
+ ```
405
+
406
+ **`usePermission(slug)`**, **`useZanzibar(request)`** and **`useAbac(request)`** each return
407
+ `{ allowed, isLoading }`. Each one runs again when its input changes. An error counts as denied.
408
+
409
+ ```tsx
410
+ const { allowed, isLoading } = usePermission('document.edit');
411
+ const editor = useZanzibar({ object: 'document:readme', relation: 'editor', subject: 'user:alice' });
412
+ const canRead = useAbac({ resourceType: 'document', action: 'read', resourceId: 'doc-123' });
413
+ ```
414
+
415
+ A Zanzibar check about a user other than the signed-in user needs the `authz:check` scope or
416
+ permission. `useAbac` needs `abac:read`; see [Core concepts](#core-concepts).
417
+
418
+ **`useMagicLink()`** returns `{ sendMagicLink, isLoading, isSent, error, reset }`:
419
+
420
+ ```tsx
421
+ function PasswordlessForm() {
422
+ const [email, setEmail] = useState('');
423
+ const { sendMagicLink, isLoading, isSent, error, reset } = useMagicLink();
424
+
425
+ if (isSent) {
426
+ return (
427
+ <p>
428
+ We sent a sign-in link to <strong>{email}</strong>.{' '}
429
+ <button onClick={reset}>Use a different email</button>
430
+ </p>
431
+ );
432
+ }
433
+
434
+ return (
435
+ <form onSubmit={(e) => { e.preventDefault(); sendMagicLink(email); }}>
436
+ <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
437
+ <button type="submit" disabled={isLoading}>{isLoading ? 'Sending…' : 'Send sign-in link'}</button>
438
+ {error && <p className="error">{error}</p>}
439
+ </form>
440
+ );
441
+ }
442
+ ```
443
+
444
+ `isSent` becomes `true` whether or not the account exists. The server never reveals that.
445
+
446
+ **`useEmailFirst()`** returns `{ checkEmail, isLoading, result, exists, reset }`. Use it to build
447
+ a sign-in screen that asks for the email address first. `checkEmail(email)` resolves to an
448
+ `EmailCheckResult`. It reports whether the account exists and which methods it can use:
449
+ `passwordEnabled`, `passkeyEnabled`, `magicLinkEnabled`, `hasPasskey`, `hasPushDevice` and
450
+ `maskedEmail`. `exists` is `null` until the first check.
451
+
452
+ ```tsx
453
+ const { checkEmail, isLoading } = useEmailFirst();
454
+
455
+ async function onSubmit(e: React.FormEvent) {
456
+ e.preventDefault();
457
+ const found = await checkEmail(email);
458
+ if (!found.exists) return showSignUp();
459
+ if (found.magicLinkEnabled) return showMagicLinkOption();
460
+ signIn(); // fall back to the LumoAuth sign-in page
461
+ }
462
+ ```
463
+
464
+ ## Common patterns
465
+
466
+ <details>
467
+ <summary><strong>A navigation bar that swaps sign-in links for the user menu</strong></summary>
468
+
469
+ ```tsx
470
+ import { SignedIn, SignedOut, UserButton, SignInButton, SignUpButton } from '@lumoauth/react';
471
+
472
+ export function Navbar() {
473
+ return (
474
+ <nav className="navbar">
475
+ <a href="/">My App</a>
476
+ <SignedOut>
477
+ <SignInButton className="btn">Sign in</SignInButton>
478
+ <SignUpButton className="btn btn-primary">Sign up</SignUpButton>
479
+ </SignedOut>
480
+ <SignedIn>
481
+ <UserButton showName />
482
+ </SignedIn>
483
+ </nav>
484
+ );
485
+ }
486
+ ```
487
+
488
+ </details>
489
+
490
+ <details>
491
+ <summary><strong>A route that needs a signed-in user</strong></summary>
492
+
493
+ ```tsx
494
+ import { SignedIn, SignedOut, RedirectToSignIn } from '@lumoauth/react';
495
+
496
+ export function ProtectedRoute({ children }: { children: React.ReactNode }) {
497
+ return (
498
+ <>
499
+ <SignedOut><RedirectToSignIn /></SignedOut>
500
+ <SignedIn>{children}</SignedIn>
501
+ </>
502
+ );
503
+ }
504
+ ```
505
+
506
+ </details>
507
+
508
+ <details>
509
+ <summary><strong>Calling your API with the user's token</strong></summary>
510
+
511
+ ```tsx
512
+ import { useSession } from '@lumoauth/react';
513
+ import { useEffect, useState } from 'react';
514
+
515
+ export function DataView() {
516
+ const { isActive, getToken } = useSession();
517
+ const [data, setData] = useState(null);
518
+
519
+ useEffect(() => {
520
+ if (!isActive) return;
521
+ getToken().then((token) =>
522
+ fetch('/api/data', { headers: { Authorization: `Bearer ${token}` } })
523
+ .then((r) => r.json())
524
+ .then(setData),
525
+ );
526
+ }, [isActive, getToken]);
527
+
528
+ return data ? <pre>{JSON.stringify(data, null, 2)}</pre> : <p>Loading…</p>;
529
+ }
530
+ ```
531
+
532
+ </details>
533
+
534
+ ## Appearance
535
+
536
+ Every ready-made component accepts an `appearance` prop:
537
+
538
+ ```tsx
539
+ <SignIn appearance={{
540
+ theme: 'dark',
541
+ className: 'my-card',
542
+ variables: { '--la-primary': '#6366f1' },
543
+ }} />
544
+ ```
545
+
546
+ | Option | Type | Description |
547
+ |---|---|---|
548
+ | `theme` | `'light' \| 'dark'` | Force a theme. The default follows the system setting. |
549
+ | `className` | `string` | Extra class on the component's root element |
550
+ | `variables` | `Record<string, string>` | Values for CSS custom properties |
551
+
552
+ Commonly changed properties: `--la-primary`, `--la-primary-hover`, `--la-bg`,
553
+ `--la-text-primary`, `--la-text-secondary`, `--la-border`, `--la-radius-md` and
554
+ `--la-font-family`. The stylesheet defines more for spacing, shadows, font sizes and states.
555
+
556
+ ## Sign-in strategies
557
+
558
+ **PKCE (default).** The user goes to the LumoAuth sign-in page and comes back to your callback
559
+ route. This is the right choice for browser apps. LumoAuth handles passwords, passkeys, social
560
+ sign-in and MFA on that page.
561
+
562
+ **Password.** `authStrategy="password"` shows an email and password form in `<SignIn>` and uses
563
+ the older resource-owner password grant. The organization must allow it. Use PKCE for new apps.
564
+
565
+ ```tsx
566
+ <LumoAuthProvider domain="https://app.lumoauth.dev" orgId="acme-corp" clientId="abc" authStrategy="password">
567
+ ```
568
+
569
+ To keep your own form but still use PKCE, call `useLumoAuth().auth.loginWithPassword()` and then
570
+ `signIn()`. The [client README](../client/README.md#passwordless-email-first-and-embedded-sign-in)
571
+ explains the flow, and the example app shows it on its `/embedded` page.
572
+
573
+ ## Errors
574
+
575
+ The hooks and `<Protect>` catch errors and report them as `allowed: false`. `<AuthCallback>`
576
+ shows sign-in errors through its `error` prop. When you call the client from `useLumoAuth()`
577
+ yourself, it throws the error classes that are described in the
578
+ [client README](../client/README.md#errors). For example, a missing scope throws a
579
+ `LumoAuthPermissionDeniedError` with `requiredScopes`.
580
+
581
+ ## API reference
582
+
583
+ | Export | Kind | Purpose |
584
+ |---|---|---|
585
+ | `LumoAuthProvider` | provider | Holds the session. Wrap the app once. |
586
+ | `SignIn`, `SignUp` | component | Sign-in and sign-up cards |
587
+ | `AuthCallback` | component | Finishes sign-in on the callback route |
588
+ | `UserButton`, `UserAvatar`, `UserProfile` | component | User menu, avatar and profile card |
589
+ | `Protect` | component | Renders children when a permission, relationship or policy allows it |
590
+ | `SignedIn`, `SignedOut` | component | Render by sign-in state |
591
+ | `RedirectToSignIn` | component | Starts sign-in when rendered |
592
+ | `SignInButton`, `SignUpButton`, `SignOutButton` | component | Unstyled triggers |
593
+ | `useAuth()` | hook | Full auth context |
594
+ | `useUser()` | hook | `LumoAuthUser \| null` |
595
+ | `useSignIn()` | hook | `{ signIn, signInWithRedirect, isLoading }` |
596
+ | `useSession()` | hook | `{ isActive, isLoaded, getToken, status }` |
597
+ | `useLumoAuth()` | hook | A `LumoAuth` client that uses the session token |
598
+ | `usePermission(slug)` | hook | `{ allowed, isLoading }` |
599
+ | `useZanzibar(request)` | hook | `{ allowed, isLoading }` |
600
+ | `useAbac(request)` | hook | `{ allowed, isLoading }`; needs `abac:read` |
601
+ | `useMagicLink()` | hook | `{ sendMagicLink, isLoading, isSent, error, reset }` |
602
+ | `useEmailFirst()` | hook | `{ checkEmail, isLoading, result, exists, reset }` |
603
+ | `LumoAuth` | class | The browser client, re-exported from `@lumoauth/client` |
604
+
605
+ The prop and return types are exported too, for example `LumoAuthProviderProps`,
606
+ `LumoAuthUser`, `ProtectProps` and `UseEmailFirstReturn`.
607
+
608
+ ## Troubleshooting
609
+
610
+ | Symptom | Cause | Fix |
611
+ |---|---|---|
612
+ | `useAbac` and `<Protect abac={…}>` always deny | The token lacks `abac:read`. | Add `abac:read` to the provider's `scope` prop and to the OAuth client's allowed scopes, then sign in again. |
613
+ | `listSlugs()` throws `403` with `requiredScopes: ['authz:read']` | The token lacks `authz:read`. | Add `authz:read` to the `scope` prop and to the OAuth client, then sign in again. |
614
+ | `<Protect zanzibar={…}>` denies a user who has the relation | The tuple names the user by a different ID than the `sub` claim. | Write the tuple with the user's `sub`, or pass `subject` yourself. |
615
+ | `useZanzibar` about another user always denies | Asking about another subject needs `authz:check`. | Run that check on your server with a credential that holds `authz:check`. |
616
+ | The callback page shows a CORS error | Your origin is not in the OAuth client's allowed origins. | Add it in the LumoAuth dashboard. |
617
+ | The callback fails with a redirect URI error | `redirectUri` does not match a registered redirect URI exactly. | Register `<origin>/auth/callback`, or pass the registered value as `redirectUri`. |
618
+ | After sign-out, the user is signed straight back in | `afterSignOutUrl` is not a registered post-logout redirect URI, so the LumoAuth session did not end. | Register the URL on the OAuth client. |
619
+ | `signUp()` throws in password mode | Inline registration is not available. | Use PKCE mode, which sends the user to the registration page. |
620
+ | The page shows signed-out content first, then the user | A client-side provider must load the session after the page renders. | Use `@lumoauth/nextjs` for server-rendered sessions. |
621
+
622
+ ## Versioning and compatibility
623
+
624
+ This package is version 1.0.0. It needs LumoAuth server API 1.0.0 or newer, React 18 or newer,
625
+ and `@lumoauth/client` 1.0.0.
626
+
627
+ ## Related packages
628
+
629
+ | Package | Relationship |
630
+ |---|---|
631
+ | [`@lumoauth/nextjs`](../nextjs/README.md) | Re-exports this package and adds server-side sessions for Next.js |
632
+ | [`@lumoauth/client`](../client/README.md) | The client, session runtime and storage adapters underneath |
633
+ | [`@lumoauth/express`](../express/README.md), [`@lumoauth/backend`](../backend/README.md) | Server side |
634
+ | [`create-lumo-agent`](../create-lumo-agent/README.md) | Creates a Next.js agent app that uses this package for sign-in |
635
+ | [Workspace README](../../README.md) | How the packages fit together |
636
+
637
+ More: [React quickstart](https://docs.lumoauth.dev/quickstarts/react/),
638
+ [SDK overview](https://docs.lumoauth.dev/developer/sdks/), and the
639
+ [example app](../../examples/nextjs/README.md), which uses every component and hook.
640
+
641
+ ## Licence
642
+
643
+ [MIT](./LICENSE)